@qawolf/cli 1.28.0 → 1.29.0

package/dist/cli.js

@@ -21213,7 +21213,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.28.0",
+  version: "1.29.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -33913,27 +33913,50 @@ async function handleRunnerInspect(ctx, options, deps) {
 }
 
 // src/core/interactiveRunner/inspectMobileRequest.ts
+var blankInspectMobileFlags = {
+  context: undefined,
+  partial: undefined,
+  selector: undefined,
+  strategy: undefined,
+  text: undefined,
+  x: undefined,
+  y: undefined
+};
 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
-    };
+var groupsOf = (flags) => ({
+  point: flags.x !== undefined || flags.y !== undefined,
+  selector: flags.selector !== undefined || flags.strategy !== undefined,
+  text: flags.text !== undefined || flags.partial !== undefined
+});
+function describeGroup(group) {
+  switch (group) {
+    case "point":
+      return "--x/--y";
+    case "selector":
+      return "--selector/--strategy";
+    case "text":
+      return "--text/--partial";
   }
-  if (flags.by === "text" && (flags.x !== undefined || flags.y !== undefined)) {
+}
+function buildInspectMobileRequest(what, flags) {
+  const groups = groupsOf(flags);
+  const present = ["point", "text", "selector"].filter((group) => groups[group]);
+  if (present.length > 1) {
     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.",
+      error: `${describeGroup(present[0])} and ${describeGroup(present[1])} were both passed, but elements are found by a point, by text, or by a selector — never more than one at once. Drop all but one of them.`,
       ok: false
     };
   }
+  const by = present[0];
   const candidate = {
     what,
-    ...flags.by === undefined ? {} : { by: flags.by },
+    ...by === undefined ? {} : { by },
     ...flags.context === undefined ? {} : { context: flags.context },
     ...flags.partial === undefined ? {} : { partial: flags.partial },
+    ...flags.selector === undefined ? {} : { selector: flags.selector },
+    ...flags.strategy === undefined ? {} : { strategy: flags.strategy },
     ...flags.text === undefined ? {} : { text: flags.text },
     ...flags.x === undefined ? {} : { x: toNumber(flags.x) },
     ...flags.y === undefined ? {} : { y: toNumber(flags.y) }
@@ -34041,46 +34064,26 @@ async function handleRunnerInspectMobile(ctx, options, deps) {
 // 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
-    },
+    flags: blankInspectMobileFlags,
     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
-    },
+    flags: blankInspectMobileFlags,
     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
-    },
+    flags: { ...blankInspectMobileFlags, context: opts.context },
     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, {
+  declareCommandKind(inspect.command("elements"), "read").description("Find elements at a screen point, carrying some text, or matching a selector").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("--selector <selector>", "Resolved the same way a screen object's own selector is").option("--strategy <strategy>", "selector: xpath, ios-predicate, or shadow (defaults to xpath)").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,
+      selector: opts.selector,
+      strategy: opts.strategy,
       text: opts.text,
       x: opts.x,
       y: opts.y
@@ -34099,8 +34102,9 @@ Examples:
   $ 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`;
+  $ qawolf runner inspect elements --x 200 --y 400
+  $ qawolf runner inspect elements --text "Sign in" --partial
+  $ qawolf runner inspect elements --selector "//android.widget.Button[@text='Sign in']"`;
 function registerRunnerInspectCommands(runner, signals) {
   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, {
@@ -35438,4 +35442,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => exitWhenIdle(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=AAB38BDE68A61B2564756E2164756E21
+//# debugId=424C032AEE2722C964756E2164756E21

package/package.json

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

package/skills/qawolf-cli/SKILL.md

@@ -179,7 +179,7 @@ that `url`; never guess a route and never send a repository link in its place.
 | `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 elements` | read | Find elements at a screen point, carrying some text, or matching a selector |
 | `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 |

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

@@ -232,8 +232,10 @@ 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
+qawolf runner inspect elements --x 240 --y 480
+qawolf runner inspect elements --text "Sign in" --partial
+qawolf runner inspect elements --selector "//android.widget.Button[@text='Sign in']"
+qawolf runner inspect elements --selector "@label == 'Sign in'" --strategy ios-predicate
 ```
 
 `session` prints one summary line — ready, or why not — because that line is
@@ -253,15 +255,21 @@ 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.
+`elements` takes one of three ways to search: whole-pixel `--x`/`--y` on the
+device's own screen, the same coordinates a screenshot is measured in;
+`--text`, which matches exactly unless `--partial` is passed; or `--selector`,
+resolved the same way a screen object's own selector is, with `--strategy`
+naming how (`xpath`, `ios-predicate` or `shadow`; defaults to `xpath`). Prefer
+`--selector` when checking a selector you are about to write: it answers what
+that exact string resolves to, where `--text`/`--x`/`--y` only approximate it.
+The three do not mix — passing flags from more than one at once is refused
+before a runner is addressed rather than silently searching by whichever one
+it picked. An unparseable selector answers `invalid-selector`, exit `2`,
+distinctly from a selector that parsed fine but matched nothing, which answers
+an empty `matches` list, exit `0` — the same distinction `highlight-selector`
+draws on a browser runner. `--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.