@qawolf/cli 2.2.1 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.js CHANGED
@@ -8405,7 +8405,7 @@ var agentMessages = {
8405
8405
  conflictingSessionList: "Pass --sessions alone, without --session or a session argument.",
8406
8406
  emptySessionList: "Pass at least one session id with --sessions.",
8407
8407
  sessionListNeedsFollow: "Pass --follow when using --sessions.",
8408
- answerSendFailed: (reason) => `The answer could not be sent: ${reason}. The session is still waiting, so try again.`,
8408
+ answerSendFailed: (reason) => `The answer could not be sent: ${reason.replace(/\.$/, "")}. The session is still waiting, so try again.`,
8409
8409
  blocked: (sessionId) => `QA Wolf asked a question and cannot continue until it is answered. Answer it with qawolf agent send "<your answer>" --session ${sessionId}.`,
8410
8410
  detachHint: "Press Ctrl-C to stop following. The session keeps running in the background.",
8411
8411
  detached: (sessionId) => `Stopped following. The session is still running — pick it back up with ${followAgain(sessionId)}.`,
@@ -8450,7 +8450,8 @@ var authErrorMessages = {
8450
8450
  notFound404Record: (noun, id) => `QA Wolf has no ${noun} ${id} (HTTP 404).`,
8451
8451
  notFound404: (noun) => noun === undefined ? "QA Wolf found nothing matching the request (HTTP 404)." : `QA Wolf found nothing matching the ${noun} request (HTTP 404).`,
8452
8452
  failedWithStatus: (status, noun) => `QA Wolf API${noun ? ` ${noun}` : ""} request failed (HTTP ${status}).`,
8453
- networkUnreachable: (baseUrl, noun) => `Could not reach the QA Wolf API at ${baseUrl}${noun ? ` to fetch ${noun}` : ""}. Check your network connection and QAWOLF_HOST_URL.`,
8453
+ notSent: "Nothing was sent, so this request did not take effect.",
8454
+ networkUnreachable: (options) => `Could not reach the QA Wolf API at ${options.baseUrl}${options.noun ? ` to fetch ${options.noun}` : ""}${options.cause ? ` (${options.cause})` : ""}. Check your network connection and QAWOLF_HOST_URL.`,
8454
8455
  timedOut: (timeoutMs, noun) => `The QA Wolf API${noun ? ` ${noun}` : ""} request timed out after ${formatSeconds(timeoutMs)}. The work may still be finishing on the platform.`,
8455
8456
  unexpectedResponse: (noun) => `Unexpected${noun ? ` ${noun}` : ""} response from the QA Wolf API.`
8456
8457
  },
@@ -8994,6 +8995,7 @@ var runMessages = {
8994
8995
  unknownStream: (stream, known) => `"${stream}" is not a stream QA Wolf writes, so this read has nothing to return. QA Wolf writes ${known.join(", ")}.`,
8995
8996
  unsearchedHistory: (stream) => `This read of ${stream} stopped before searching all of the runner's history, so older entries may exist that it did not look at. Page forwards with --since to reach them.`,
8996
8997
  submitMayHaveStarted: "The runner did not answer, which does not mean the run did not start. Read qawolf runner events run-status before running the flow again, and use the newest run id there if one appeared.",
8998
+ submitLostMayHaveStarted: "The run may have started before the connection failed. Read qawolf runner events run-status before running the flow again, and use the newest run id there if one appeared.",
8997
8999
  targetMismatch: (runnerName, requiredRunnerName) => `This flow needs a ${requiredRunnerName} runner and ${runnerName} is running. Launch one with --name ${requiredRunnerName}.`
8998
9000
  };
8999
9001
 
@@ -15447,6 +15449,37 @@ function applyWorkspaceId(inputSchema, input, workspaceId) {
15447
15449
  return { ...input, workspaceId };
15448
15450
  }
15449
15451
 
15452
+ // src/core/fetchCause.ts
15453
+ var maxCauseDepth = 5;
15454
+ var maxCauseMessageLength = 120;
15455
+ var codePattern = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
15456
+ var urlPattern = /\bhttps?:\/\/\S+/g;
15457
+ function causeChain(options) {
15458
+ const { error, remainingDepth } = options;
15459
+ const { cause } = error;
15460
+ if (!(cause instanceof Error) || remainingDepth === 0)
15461
+ return [error];
15462
+ return [
15463
+ error,
15464
+ ...causeChain({ error: cause, remainingDepth: remainingDepth - 1 })
15465
+ ];
15466
+ }
15467
+ function shortMessage(message) {
15468
+ const withoutUrls = message.replace(urlPattern, "<url>").trim();
15469
+ return withoutUrls.length > maxCauseMessageLength ? `${withoutUrls.slice(0, maxCauseMessageLength)}…` : withoutUrls;
15470
+ }
15471
+ function describeFetchCause(error) {
15472
+ const chain = causeChain({ error, remainingDepth: maxCauseDepth });
15473
+ const root = chain.at(-1);
15474
+ const code = chain.map((link) => errorCode(link)).reverse().find((candidate) => candidate !== undefined && codePattern.test(candidate));
15475
+ const message = root === undefined ? "" : shortMessage(root.message);
15476
+ if (code === undefined)
15477
+ return message || undefined;
15478
+ if (!message || message.includes(code))
15479
+ return message || code;
15480
+ return `${code}: ${message}`;
15481
+ }
15482
+
15450
15483
  // src/core/parseJson.ts
15451
15484
  function parseJson(text) {
15452
15485
  try {
@@ -15579,7 +15612,13 @@ function describeRequestError(err, baseUrl, noun, notFound) {
15579
15612
  return { error: m2.request.failedWithStatus(err.status, noun), ...body };
15580
15613
  }
15581
15614
  if (err.kind === "network") {
15582
- return { error: m2.request.networkUnreachable(baseUrl, noun) };
15615
+ return {
15616
+ error: m2.request.networkUnreachable({
15617
+ baseUrl,
15618
+ cause: describeFetchCause(err.cause),
15619
+ noun
15620
+ })
15621
+ };
15583
15622
  }
15584
15623
  if (err.kind === "timeout") {
15585
15624
  return { error: m2.request.timedOut(err.timeoutMs, noun) };
@@ -15639,9 +15678,9 @@ async function requestWithRetry(args) {
15639
15678
  const unreachable = result.error.kind === "network" || result.error.kind === "timeout";
15640
15679
  return {
15641
15680
  ok: false,
15642
- ...args.describe(result.error),
15643
15681
  ...mayHaveArrived ? { mayHaveArrived } : {},
15644
- ...unreachable ? { unreachable } : {}
15682
+ ...unreachable ? { unreachable } : {},
15683
+ ...args.describe(result.error)
15645
15684
  };
15646
15685
  }
15647
15686
  await sleep2(backoff);
@@ -15656,6 +15695,13 @@ function callPublicApi(trpc, contract, input, options) {
15656
15695
  }
15657
15696
  return trpc.mutation(path, input, contract.output, options);
15658
15697
  }
15698
+ var notSentCodes = new Set([
15699
+ "ConnectionRefused",
15700
+ "EAI_AGAIN",
15701
+ "ECONNREFUSED",
15702
+ "ENOTFOUND",
15703
+ "UND_ERR_CONNECT_TIMEOUT"
15704
+ ]);
15659
15705
  function makeCallPublicApiMethod(trpc, deps, readBackoffMs) {
15660
15706
  return async (contract, input, options) => {
15661
15707
  const sent = applyWorkspaceId(contract.input, input, deps.workspaceId);
@@ -15663,7 +15709,17 @@ function makeCallPublicApiMethod(trpc, deps, readBackoffMs) {
15663
15709
  return requestWithRetry({
15664
15710
  call: () => callPublicApi(trpc, contract, sent, options),
15665
15711
  backoffMs: contract.kind === "read" ? readBackoffMs : [],
15666
- describe: (err) => describeRequestError(err, deps.baseUrl, contract.name, subject),
15712
+ describe: (err) => {
15713
+ const failure = describeRequestError(err, deps.baseUrl, contract.name, subject);
15714
+ const code = err.kind === "network" ? errorCode(err.cause.cause) ?? errorCode(err.cause) : undefined;
15715
+ if (contract.kind !== "write" || !code || !notSentCodes.has(code))
15716
+ return failure;
15717
+ return {
15718
+ ...failure,
15719
+ error: `${failure.error} ${authMessages.errors.request.notSent}`,
15720
+ mayHaveArrived: false
15721
+ };
15722
+ },
15667
15723
  sleep: deps.sleep
15668
15724
  });
15669
15725
  };
@@ -16546,7 +16602,8 @@ function createTrpcClient(apiKey, deps) {
16546
16602
  return withLogging(path, () => sendWireRequest(deps.fetch, url, {
16547
16603
  body,
16548
16604
  headers: { ...authHeader, "content-type": "application/json" },
16549
- method: "POST"
16605
+ method: "POST",
16606
+ redirect: "error"
16550
16607
  }, schema, options?.timeoutMs ?? defaultTimeoutMs));
16551
16608
  }
16552
16609
  };
@@ -23634,7 +23691,7 @@ function startUpdateCheck(deps) {
23634
23691
  // package.json
23635
23692
  var package_default = {
23636
23693
  name: "@qawolf/cli",
23637
- version: "2.2.1",
23694
+ version: "2.3.0",
23638
23695
  description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
23639
23696
  keywords: [
23640
23697
  "automation",
@@ -23830,7 +23887,7 @@ function withAuthContext(signals, fn, deps = {}) {
23830
23887
  baseUrl: apiBaseUrl,
23831
23888
  fetch: globalThis.fetch,
23832
23889
  logger: ctx.log("trpc"),
23833
- workspaceId: resolved.workspaceId
23890
+ workspaceId: deps.workspaceId ?? resolved.workspaceId
23834
23891
  });
23835
23892
  try {
23836
23893
  const result = await fn({
@@ -38814,6 +38871,9 @@ function buildRunnerAction(type, flags) {
38814
38871
  if (to !== undefined && !to.ok)
38815
38872
  return to;
38816
38873
  const button = flags.button ?? (type === "click" ? "left" : undefined);
38874
+ const scrollsOneWay = type === "scroll" && flags.scrollX === undefined !== (flags.scrollY === undefined);
38875
+ const scrollX = flags.scrollX ?? (scrollsOneWay ? "0" : undefined);
38876
+ const scrollY = flags.scrollY ?? (scrollsOneWay ? "0" : undefined);
38817
38877
  const candidate = {
38818
38878
  type,
38819
38879
  ...button === undefined ? {} : { button },
@@ -38821,8 +38881,8 @@ function buildRunnerAction(type, flags) {
38821
38881
  ...from === undefined ? {} : { from: from.value },
38822
38882
  ...flags.keys === undefined ? {} : { keys: flags.keys },
38823
38883
  ...parsedPath === undefined ? {} : { path: parsedPath.value },
38824
- ...flags.scrollX === undefined ? {} : { scroll_x: toNumber(flags.scrollX) },
38825
- ...flags.scrollY === undefined ? {} : { scroll_y: toNumber(flags.scrollY) },
38884
+ ...scrollX === undefined ? {} : { scroll_x: toNumber(scrollX) },
38885
+ ...scrollY === undefined ? {} : { scroll_y: toNumber(scrollY) },
38826
38886
  ...flags.selector === undefined ? {} : { selector: flags.selector },
38827
38887
  ...flags.strategy === undefined ? {} : { strategy: flags.strategy },
38828
38888
  ...flags.text === undefined ? {} : { text: flags.text },
@@ -39367,6 +39427,20 @@ function makeInteractiveRunnerDeps(options) {
39367
39427
 
39368
39428
  // src/commands/runner/context.ts
39369
39429
  var runnerFlagDescription = "Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored runner";
39430
+ function workspaceIdOption() {
39431
+ return new Option2("--workspace-id <id>", "Workspace to work in for this command only. Defaults to the one 'qawolf auth switch' saved, and is never saved itself").argParser((value) => {
39432
+ const trimmed = value.trim();
39433
+ if (!trimmed)
39434
+ throw new InvalidArgumentError2("Give a workspace id.");
39435
+ return trimmed;
39436
+ });
39437
+ }
39438
+ function withRunnerContext(signals, fn, deps = {}) {
39439
+ return (opts, command) => withAuthContext(signals, fn, {
39440
+ ...deps,
39441
+ workspaceId: command.optsWithGlobals().workspaceId
39442
+ })(opts, command);
39443
+ }
39370
39444
  function runnerDeps(ctx) {
39371
39445
  return makeInteractiveRunnerDeps({
39372
39446
  cwd: process.cwd(),
@@ -39384,7 +39458,7 @@ Every action in a see-and-act loop is followed by a look at the result, so ask f
39384
39458
 
39385
39459
  Coordinates are pixels on the same screenshot you just read. The runner serves one see-or-act request at a time, so never have two in flight; when the next few steps are already known, send them as one \`runner actions\` sequence instead. Bounds are checked before anything is sent, so an over-long --text or an out-of-range coordinate comes back immediately naming the limit.
39386
39460
 
39387
- On a 4, the answer may have been lost with the action in flight: take a screenshot before repeating a click, and repeat only what the screen says did not happen.
39461
+ On a 4, unless the message says nothing was sent, the answer may have been lost with the action in flight: take a screenshot before repeating a click, and repeat only what the screen says did not happen.
39388
39462
 
39389
39463
  # Mobile
39390
39464
 
@@ -39669,7 +39743,7 @@ Both succeed when there was nothing to do, and say which: \`wasRunning\` is fals
39669
39743
  `;
39670
39744
 
39671
39745
  // src/commands/runner/guides/workflow.md
39672
- var workflow_default = "An interactive runner is a live pod with a browser or a mobile device in it. You launch one, look at it, act on it, run flows on it, and read what it recorded. Everything is a plain request to one host, so there is no connection to hold open. This guide covers what spans commands; each command's own help below covers the rest.\n\n## Which runner a command reaches\n\nCommands that target a runner find one in this order: `--runner`, then `QAWOLF_RUNNER_ID`, then the runner stored for the current directory, which `qawolf runner launch` sets. Setting the environment variable once is the most robust for a harness whose working directory may not be stable, with two catches:\n\n- `qawolf runner launch` is not in that order: it takes its id from `--id` and never reads `QAWOLF_RUNNER_ID`. Pass `--id` whenever you have an id in mind.\n- A runner id that is set is treated as found, whether or not anything is running under it. Exporting `QAWOLF_RUNNER_ID=agent-1` turns off the auto-launch described next: instead of starting `agent-1`, commands try to reach it and fail with exit code `8`, naming the id and saying the variable is what chose it. Launch that id once yourself and the rest follows.\n\nIf nothing names a runner, the commands that change something launch one and say so on stderr, naming it: `run`, `act`, `actions` and `exec`. Read that announcement. The browser it just started is fresh: nothing has been run on it, nothing is signed in, and it shows only the QA Wolf welcome page. Acting as though your earlier setup survived is the single most likely way to drive the wrong page.\n\nNo 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`.\n\n## The order that matters\n\nA playwright runner's screen starts as it launches, showing a QA Wolf welcome page, so the screenshot-and-act loop works before you run anything.\n\nAny other runner, such as a mobile one, has no screen until its first run, and nothing else starts it. Until you have run something on it, `screenshot` and `act` fail with exit code `2`. That is not a fault, and it does not clear on its own: run a flow with `qawolf runner run <flow>`, which needs a flow file and a `package.json` on disk.\n\n## Exit codes\n\nRetry on the exit code, not on the message text:\n\n- `4` is transient, with one exception. The screen cannot serve this instant: still coming up just after launch, restarting after a display-size change, or busy with another request. Retry in a second or two, and bound the retries. The exception is a command that changes something, where a `4` can instead mean the answer was lost with the work in flight. For `act` and `actions`, take a screenshot first and repeat only what the screen says did not happen. For `run`, poll `run-status` instead of submitting again, since a second submission risks a second billed run. For `exec`, check the effect the snippet was meant to have before running it again.\n- `6` means the work ran out of the time it is given.\n- `7` means billing prevented the request, such as a plan that does not cover the runner you asked for. The message says what was refused and what clears it.\n- `8` means there is no such runner. It was never launched, or it was terminated, or it idled out. Retrying never brings one back, so stop and launch the id or name one that is running. The message says which runner was meant and whether `--runner`, `QAWOLF_RUNNER_ID` or this directory's stored default chose it; read that line before you pick an id to launch.\n- `2` will not clear on its own. Nothing has run on this runner yet, so run a flow; or the runner has no browser at all, so launch with `--name playwright` instead; or the action belongs to the other runner family, so send `tap`, `swipe` or `fill` to a mobile runner and the browser actions to a browser runner. The message says which.\n\n`act`, `actions`, `run` and `exec` are the commands whose lost answer may still have taken effect.\n\n## End to end\n\nRun from a directory holding a flow and a `package.json`.\n\n```sh\nexport QAWOLF_API_KEY=... # the only credential\nexport QAWOLF_RUNNER_ID=agent-1 # so no command below needs --runner\n\nqawolf runner launch --id agent-1 --json # --id, not the variable; read .alreadyRunning and .url\nqawolf runner run flows/smoke.flow.ts --follow # exit 1 if it failed\n\nqawolf runner act navigate --url https://example.com/login --screenshot step-1.jpg # then read step-1.jpg yourself\nqawolf runner act click --button left --x 480 --y 260 --screenshot step-2.jpg\nqawolf runner act type --text \"someone@example.com\" --screenshot step-3.jpg\n\nqawolf runner inspect element-html --selector \"#email\"\nqawolf runner inspect variable --name cart | jq .total\n\nqawolf runner run flows/smoke.flow.ts --lines 12-40 --follow # just those lines\nqawolf runner events recorder --tail 5 | jq -r '[.locator] + (.alternates // []) | @tsv'\nqawolf runner terminate\n```\n\nOn a mobile runner, launch with `--name android` or `--name ios`, and drive it with `tap`, `swipe`, `fill` and `type` instead of the browser actions.\n";
39746
+ var workflow_default = "An interactive runner is a live pod with a browser or a mobile device in it. You launch one, look at it, act on it, run flows on it, and read what it recorded. Everything is a plain request to one host, so there is no connection to hold open. This guide covers what spans commands; each command's own help below covers the rest.\n\n## Which runner a command reaches\n\nEvery runner command works in the workspace `qawolf auth switch` saved, unless it is given `--workspace-id <id>`. The flag holds for that one command and is never saved, so sessions on one machine working on different workspaces do not move each other. Since runner ids are scoped to a team, pass the same `--workspace-id` to every command that drives a runner you launched with it; leave it off one and that command looks for the runner in the saved workspace.\n\nCommands that target a runner find one in this order: `--runner`, then `QAWOLF_RUNNER_ID`, then the runner stored for the current directory, which `qawolf runner launch` sets. Setting the environment variable once is the most robust for a harness whose working directory may not be stable, with two catches:\n\n- `qawolf runner launch` is not in that order: it takes its id from `--id` and never reads `QAWOLF_RUNNER_ID`. Pass `--id` whenever you have an id in mind.\n- A runner id that is set is treated as found, whether or not anything is running under it. Exporting `QAWOLF_RUNNER_ID=agent-1` turns off the auto-launch described next: instead of starting `agent-1`, commands try to reach it and fail with exit code `8`, naming the id and saying the variable is what chose it. Launch that id once yourself and the rest follows.\n\nIf nothing names a runner, the commands that change something launch one and say so on stderr, naming it: `run`, `act`, `actions` and `exec`. Read that announcement. The browser it just started is fresh: nothing has been run on it, nothing is signed in, and it shows only the QA Wolf welcome page. Acting as though your earlier setup survived is the single most likely way to drive the wrong page.\n\nNo 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`.\n\n## The order that matters\n\nA playwright runner's screen starts as it launches, showing a QA Wolf welcome page, so the screenshot-and-act loop works before you run anything.\n\nAny other runner, such as a mobile one, has no screen until its first run, and nothing else starts it. Until you have run something on it, `screenshot` and `act` fail with exit code `2`. That is not a fault, and it does not clear on its own: run a flow with `qawolf runner run <flow>`, which needs a flow file and a `package.json` on disk.\n\n## Exit codes\n\nRetry on the exit code:\n\n- `4` is transient, with one exception. The screen cannot serve this instant: still coming up just after launch, restarting after a display-size change, or busy with another request. Retry in a second or two, and bound the retries. The exception is a command that changes something, where a `4` can instead mean the answer was lost with the work in flight, unless the message says nothing was sent. For `act` and `actions`, take a screenshot first and repeat only what the screen says did not happen. For `run`, poll `run-status` instead of submitting again, since a second submission risks a second billed run. For `exec`, check the effect the snippet was meant to have before running it again.\n- `6` means the work ran out of the time it is given.\n- `7` means billing prevented the request, such as a plan that does not cover the runner you asked for. The message says what was refused and what clears it.\n- `8` means there is no such runner. It was never launched, or it was terminated, or it idled out. Retrying never brings one back, so stop and launch the id or name one that is running. The message says which runner was meant and whether `--runner`, `QAWOLF_RUNNER_ID` or this directory's stored default chose it; read that line before you pick an id to launch.\n- `2` will not clear on its own. Nothing has run on this runner yet, so run a flow; or the runner has no browser at all, so launch with `--name playwright` instead; or the action belongs to the other runner family, so send `tap`, `swipe` or `fill` to a mobile runner and the browser actions to a browser runner. The message says which.\n\n`act`, `actions`, `run` and `exec` are the commands whose lost answer may still have taken effect.\n\n## End to end\n\nRun from a directory holding a flow and a `package.json`.\n\n```sh\nexport QAWOLF_API_KEY=... # the only credential\nexport QAWOLF_RUNNER_ID=agent-1 # so no command below needs --runner\n\nqawolf runner launch --id agent-1 --json # --id, not the variable; read .alreadyRunning and .url\nqawolf runner run flows/smoke.flow.ts --follow # exit 1 if it failed\n\nqawolf runner act navigate --url https://example.com/login --screenshot step-1.jpg # then read step-1.jpg yourself\nqawolf runner act click --button left --x 480 --y 260 --screenshot step-2.jpg\nqawolf runner act type --text \"someone@example.com\" --screenshot step-3.jpg\n\nqawolf runner inspect element-html --selector \"#email\"\nqawolf runner inspect variable --name cart | jq .total\n\nqawolf runner run flows/smoke.flow.ts --lines 12-40 --follow # just those lines\nqawolf runner events recorder --tail 5 | jq -r '[.locator] + (.alternates // []) | @tsv'\nqawolf runner terminate\n```\n\nOn a mobile runner, launch with `--name android` or `--name ios`, and drive it with `tap`, `swipe`, `fill` and `type` instead of the browser actions.\n";
39673
39747
 
39674
39748
  // src/commands/runner/guides/index.ts
39675
39749
  var runnerGuides = {
@@ -39704,7 +39778,7 @@ Mobile:
39704
39778
  $ qawolf runner actions '[{"type":"tap","selector":"//*[@content-desc=\\"Email\\"]"},{"type":"type","text":"hello@example.com"},{"type":"tap","x":540,"y":1650}]' --screenshot after-login.jpg
39705
39779
  $ qawolf runner actions '[{"type":"fill","selector":"name == \\"Postal code\\"","strategy":"ios-predicate","text":"94107"},{"type":"swipe","from":{"x":540,"y":1600},"to":{"x":540,"y":600}}]'`;
39706
39780
  function registerRunnerActionsCommand(runner, signals) {
39707
- declareCommandKind(runner.command("actions <sequence>"), "write").description("Perform a sequence of up to ten raw actions on a runner's screen in one request, as a JSON array of the same actions `runner act` takes. Use - to read the array from stdin. Actions run back to back, so batch only steps whose targets are on the screen you last saw, and end the sequence at the step that changes the page. Each result carries an effect: performed, not-performed, or unknown when the runner stopped answering and the action may have landed").option("--continue-on-failure", "Carry on past an action that reached the runner and did not take effect; a runner that cannot be reached or a screen that cannot serve still ends the sequence").option("--runner <id>", runnerFlagDescription).option("--screenshot <path>", "Save a JPEG of the screen after the last action to this file. With --screenshot-mode each, one file per action, with the action's index before the extension. - writes the final frame to stdout and moves the confirmation to stderr").addOption(new Option2("--screenshot-mode <mode>", "Defaults to final when --screenshot is given, none otherwise").choices([...screenshotModes])).addHelpText("after", actionsExamples).addHelpText("after", runnerGuides.actions).action((sequence, opts, command) => withAuthContext(signals, (ctx) => handleRunnerActions(ctx, {
39781
+ declareCommandKind(runner.command("actions <sequence>"), "write").description("Perform a sequence of up to ten raw actions on a runner's screen in one request, as a JSON array of the same actions `runner act` takes. Use - to read the array from stdin. Actions run back to back, so batch only steps whose targets are on the screen you last saw, and end the sequence at the step that changes the page. Each result carries an effect: performed, not-performed, or unknown when the runner stopped answering and the action may have landed").option("--continue-on-failure", "Carry on past an action that reached the runner and did not take effect; a runner that cannot be reached or a screen that cannot serve still ends the sequence").option("--runner <id>", runnerFlagDescription).option("--screenshot <path>", "Save a JPEG of the screen after the last action to this file. With --screenshot-mode each, one file per action, with the action's index before the extension. - writes the final frame to stdout and moves the confirmation to stderr").addOption(new Option2("--screenshot-mode <mode>", "Defaults to final when --screenshot is given, none otherwise").choices([...screenshotModes])).addHelpText("after", actionsExamples).addHelpText("after", runnerGuides.actions).action((sequence, opts, command) => withRunnerContext(signals, (ctx) => handleRunnerActions(ctx, {
39708
39782
  actions: sequence,
39709
39783
  continueOnFailure: opts.continueOnFailure === true,
39710
39784
  runner: opts.runner,
@@ -39875,7 +39949,7 @@ Examples:
39875
39949
  $ echo 'console.log(await page.title())' | qawolf runner exec -
39876
39950
  $ qawolf runner exec snippet.ts --file flows/checkout.flow.ts`;
39877
39951
  function registerRunnerExecCommand(runner, signals) {
39878
- declareCommandKind(runner.command("exec <file>"), "write").description("Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin").option("--file <path>", "File whose scope the snippet is evaluated in; it and the directory's other files travel with it").option("--runner <id>", runnerFlagDescription).addHelpText("after", execExamples).addHelpText("after", runnerGuides.exec).action((file, opts, command) => withAuthContext(signals, (ctx) => handleRunnerExec(ctx, { contextFile: opts.file, runner: opts.runner, source: file }, runnerDeps(ctx)))(opts, command));
39952
+ declareCommandKind(runner.command("exec <file>"), "write").description("Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin").option("--file <path>", "File whose scope the snippet is evaluated in; it and the directory's other files travel with it").option("--runner <id>", runnerFlagDescription).addHelpText("after", execExamples).addHelpText("after", runnerGuides.exec).action((file, opts, command) => withRunnerContext(signals, (ctx) => handleRunnerExec(ctx, { contextFile: opts.file, runner: opts.runner, source: file }, runnerDeps(ctx)))(opts, command));
39879
39953
  }
39880
39954
 
39881
39955
  // src/domains/interactiveRunner/highlightSelector.ts
@@ -39950,7 +40024,7 @@ Examples:
39950
40024
  $ qawolf runner highlight-selector "#checkout" && qawolf runner screenshot
39951
40025
  $ qawolf runner highlight-selector`;
39952
40026
  function registerRunnerHighlightSelectorCommand(runner, signals) {
39953
- declareCommandKind(runner.command("highlight-selector [selector]"), "write").description("Highlight what a selector matches on a runner's live page, so the next screenshot shows it. Omit the selector to clear the highlight").option("--runner <id>", runnerFlagDescription).addHelpText("after", highlightExamples).addHelpText("after", runnerGuides.highlightSelector).action((selector, opts, command) => withAuthContext(signals, (ctx) => handleRunnerHighlightSelector(ctx, { runner: opts.runner, selector }, runnerDeps(ctx)))(opts, command));
40027
+ declareCommandKind(runner.command("highlight-selector [selector]"), "write").description("Highlight what a selector matches on a runner's live page, so the next screenshot shows it. Omit the selector to clear the highlight").option("--runner <id>", runnerFlagDescription).addHelpText("after", highlightExamples).addHelpText("after", runnerGuides.highlightSelector).action((selector, opts, command) => withRunnerContext(signals, (ctx) => handleRunnerHighlightSelector(ctx, { runner: opts.runner, selector }, runnerDeps(ctx)))(opts, command));
39954
40028
  }
39955
40029
 
39956
40030
  // src/domains/interactiveRunner/importPackage.ts
@@ -40061,7 +40135,7 @@ Examples:
40061
40135
  $ qawolf runner import-package dayjs
40062
40136
  $ qawolf runner import-package dayjs --package-version 1.11.13`;
40063
40137
  function registerRunnerImportPackageCommand(runner, signals) {
40064
- declareCommandKind(runner.command("import-package <name>"), "write").description("Install a package into a runner's live run, so a snippet or a selection can import it").option("--package-version <version>", "Version to install", "latest").option("--runner <id>", runnerFlagDescription).addHelpText("after", importPackageExamples).addHelpText("after", runnerGuides.importPackage).action((name, opts, command) => withAuthContext(signals, (ctx) => handleRunnerImportPackage(ctx, { name, runner: opts.runner, version: opts.packageVersion }, runnerDeps(ctx)))(opts, command));
40138
+ declareCommandKind(runner.command("import-package <name>"), "write").description("Install a package into a runner's live run, so a snippet or a selection can import it").option("--package-version <version>", "Version to install", "latest").option("--runner <id>", runnerFlagDescription).addHelpText("after", importPackageExamples).addHelpText("after", runnerGuides.importPackage).action((name, opts, command) => withRunnerContext(signals, (ctx) => handleRunnerImportPackage(ctx, { name, runner: opts.runner, version: opts.packageVersion }, runnerDeps(ctx)))(opts, command));
40065
40139
  }
40066
40140
 
40067
40141
  // src/core/interactiveRunner/inspectRequest.ts
@@ -40278,22 +40352,22 @@ async function handleRunnerInspectMobile(ctx, options, deps) {
40278
40352
 
40279
40353
  // src/commands/runner/inspectMobile.register.ts
40280
40354
  function registerRunnerInspectMobileCommands(inspect, signals) {
40281
- 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, {
40355
+ declareCommandKind(inspect.command("session"), "read").description("Print the Appium session's status: ready, or why not").option("--runner <id>", runnerFlagDescription).action((opts, command) => withRunnerContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
40282
40356
  flags: blankInspectMobileFlags,
40283
40357
  runner: opts.runner,
40284
40358
  what: "session"
40285
40359
  }, runnerDeps(ctx)))(opts, command));
40286
- 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, {
40360
+ declareCommandKind(inspect.command("contexts"), "read").description("List the WebView contexts available, and which is current").option("--runner <id>", runnerFlagDescription).action((opts, command) => withRunnerContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
40287
40361
  flags: blankInspectMobileFlags,
40288
40362
  runner: opts.runner,
40289
40363
  what: "contexts"
40290
40364
  }, runnerDeps(ctx)))(opts, command));
40291
- 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, {
40365
+ 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) => withRunnerContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
40292
40366
  flags: { ...blankInspectMobileFlags, context: opts.context },
40293
40367
  runner: opts.runner,
40294
40368
  what: "page"
40295
40369
  }, runnerDeps(ctx)))(opts, command));
40296
- 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, {
40370
+ 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) => withRunnerContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
40297
40371
  flags: {
40298
40372
  context: opts.context,
40299
40373
  partial: opts.partial,
@@ -40322,17 +40396,17 @@ Examples:
40322
40396
  $ qawolf runner inspect elements --selector "//android.widget.Button[@text='Sign in']"`;
40323
40397
  function registerRunnerInspectCommands(runner, signals) {
40324
40398
  const inspect = runner.command("inspect").description("Read one thing off a runner's live page (browser) or Appium session (mobile)").addHelpText("after", inspectExamples).addHelpText("after", runnerGuides.inspect);
40325
- 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, {
40399
+ 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) => withRunnerContext(signals, (ctx) => handleRunnerInspect(ctx, {
40326
40400
  flags: { name: undefined, selector: opts.selector },
40327
40401
  runner: opts.runner,
40328
40402
  what: "element-html"
40329
40403
  }, runnerDeps(ctx)))(opts, command));
40330
- declareCommandKind(inspect.command("page-html"), "read").description("Print the page's HTML, simplified for a model to read").option("--selector <selector>", "Limit the output to this subtree").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspect(ctx, {
40404
+ declareCommandKind(inspect.command("page-html"), "read").description("Print the page's HTML, simplified for a model to read").option("--selector <selector>", "Limit the output to this subtree").option("--runner <id>", runnerFlagDescription).action((opts, command) => withRunnerContext(signals, (ctx) => handleRunnerInspect(ctx, {
40331
40405
  flags: { name: undefined, selector: opts.selector },
40332
40406
  runner: opts.runner,
40333
40407
  what: "page-html"
40334
40408
  }, runnerDeps(ctx)))(opts, command));
40335
- declareCommandKind(inspect.command("variable"), "read").description("Print a top-level variable's value from the running workflow").requiredOption("--name <name>", "Name of the variable to read").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspect(ctx, {
40409
+ declareCommandKind(inspect.command("variable"), "read").description("Print a top-level variable's value from the running workflow").requiredOption("--name <name>", "Name of the variable to read").option("--runner <id>", runnerFlagDescription).action((opts, command) => withRunnerContext(signals, (ctx) => handleRunnerInspect(ctx, {
40336
40410
  flags: { name: opts.name, selector: undefined },
40337
40411
  runner: opts.runner,
40338
40412
  what: "variable"
@@ -40594,6 +40668,7 @@ Examples:
40594
40668
  $ qawolf runner act click --button left --x 480 --y 260
40595
40669
  $ qawolf runner act type --text "hello@example.com"
40596
40670
  $ qawolf runner act keypress --keys Control a
40671
+ $ qawolf runner act scroll --x 640 --y 400 --scroll-y 600
40597
40672
  $ qawolf runner act navigate --url https://example.com
40598
40673
  $ qawolf runner act drag --path '[{"x":10,"y":20},{"x":80,"y":90}]'
40599
40674
  $ qawolf runner act click --button left --x 480 --y 260 --screenshot step-4.jpg
@@ -40606,17 +40681,19 @@ Mobile:
40606
40681
  $ qawolf runner act fill --selector 'name == "Postal code"' --strategy ios-predicate --text 94107
40607
40682
  $ qawolf runner act swipe --from 540,1600 --to 540,600 --duration-ms 1500`;
40608
40683
 
40609
- // src/commands/runner/interact.register.ts
40610
- var defaultScreenshotPath = "screenshot.jpg";
40684
+ // src/commands/runner/screenshotExamples.ts
40611
40685
  var screenshotExamples = `
40612
40686
  Examples:
40613
40687
  $ qawolf runner screenshot
40614
40688
  $ qawolf runner screenshot --out screens/step-3.jpg
40615
40689
  $ qawolf runner screenshot --out - > step-3.jpg
40616
40690
  $ qawolf runner screenshot --out - | my-vision-tool`;
40691
+
40692
+ // src/commands/runner/interact.register.ts
40693
+ var defaultScreenshotPath = "screenshot.jpg";
40617
40694
  function registerRunnerInteractCommands(runner, signals) {
40618
- declareCommandKind(runner.command("screenshot"), "read").description("Save a JPEG of an interactive runner's screen to a file, or write it to stdout with --out -").option("--out <path>", "File to write the image to. - writes the JPEG bytes to stdout on their own and moves the confirmation, JSON included, to stderr", defaultScreenshotPath).option("--runner <id>", runnerFlagDescription).addHelpText("after", screenshotExamples).addHelpText("after", runnerGuides.screenshot).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerScreenshot(ctx, { out: opts.out, runner: opts.runner }, runnerDeps(ctx)))(opts, command));
40619
- declareCommandKind(runner.command("act <action>"), "write").description("Perform one raw action on a runner's screen. A browser runner takes click, double_click, scroll, move, drag, keypress, navigate and type; a mobile runner takes tap, swipe, fill and type. A browser runner answers mobile actions with action-not-supported-on-browser; a mobile runner answers the other browser actions with action-not-supported-on-mobile. Use - to read a whole action as JSON from stdin").option("--button <button>", "click: left (default), right, wheel, back or forward").option("--duration-ms <ms>", "swipe: how long it takes, up to 10000. Slow scrolls, fast flings").option("--from <x,y>", "swipe: the point it starts at").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("--screenshot <path>", "Also save a JPEG of the screen, taken after the action, to this file, in place of a separate screenshot. An action that did not take effect answers with one too. - writes it to stdout and moves the confirmation, JSON included, to stderr").option("--scroll-x <delta>", "scroll: horizontal wheel delta").option("--scroll-y <delta>", "scroll: vertical wheel delta").option("--selector <selector>", "tap or fill: the element to act on, as a screen object would find it. tap takes it in place of --x and --y").option("--strategy <strategy>", "how --selector is resolved: xpath (default), ios-predicate or shadow").option("--text <text>", "type: the text to type into what has focus. fill: the field's new value").option("--to <x,y>", "swipe: the point it ends at").option("--url <url>", "navigate: the http or https URL to go to").option("--x <pixels>", "click, tap and the like: x, in screenshot pixels").option("--y <pixels>", "click, tap and the like: y, in screenshot pixels").addHelpText("after", actExamples).addHelpText("after", runnerGuides.act).action((action, opts, command) => withAuthContext(signals, (ctx) => handleRunnerAct(ctx, {
40695
+ declareCommandKind(runner.command("screenshot"), "read").description("Save a JPEG of an interactive runner's screen to a file, or write it to stdout with --out -").option("--out <path>", "File to write the image to. - writes the JPEG bytes to stdout on their own and moves the confirmation, JSON included, to stderr", defaultScreenshotPath).option("--runner <id>", runnerFlagDescription).addHelpText("after", screenshotExamples).addHelpText("after", runnerGuides.screenshot).action((opts, command) => withRunnerContext(signals, (ctx) => handleRunnerScreenshot(ctx, { out: opts.out, runner: opts.runner }, runnerDeps(ctx)))(opts, command));
40696
+ declareCommandKind(runner.command("act <action>"), "write").description("Perform one raw action on a runner's screen. A browser runner takes click, double_click, scroll, move, drag, keypress, navigate and type; a mobile runner takes tap, swipe, fill and type. A browser runner answers mobile actions with action-not-supported-on-browser; a mobile runner answers the other browser actions with action-not-supported-on-mobile. Use - to read a whole action as JSON from stdin").option("--button <button>", "click: left (default), right, wheel, back or forward").option("--duration-ms <ms>", "swipe: how long it takes, up to 10000. Slow scrolls, fast flings").option("--from <x,y>", "swipe: the point it starts at").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("--screenshot <path>", "Also save a JPEG of the screen, taken after the action, to this file, in place of a separate screenshot. An action that did not take effect answers with one too. - writes it to stdout and moves the confirmation, JSON included, to stderr").option("--scroll-x <delta>", "scroll: horizontal wheel delta, 0 when only --scroll-y is given").option("--scroll-y <delta>", "scroll: vertical wheel delta, 0 when only --scroll-x is given").option("--selector <selector>", "tap or fill: the element to act on, as a screen object would find it. tap takes it in place of --x and --y").option("--strategy <strategy>", "how --selector is resolved: xpath (default), ios-predicate or shadow").option("--text <text>", "type: the text to type into what has focus. fill: the field's new value").option("--to <x,y>", "swipe: the point it ends at").option("--url <url>", "navigate: the http or https URL to go to").option("--x <pixels>", "click, tap and the like: x, in screenshot pixels").option("--y <pixels>", "click, tap and the like: y, in screenshot pixels").addHelpText("after", actExamples).addHelpText("after", runnerGuides.act).action((action, opts, command) => withRunnerContext(signals, (ctx) => handleRunnerAct(ctx, {
40620
40697
  flags: {
40621
40698
  button: opts.button,
40622
40699
  durationMs: opts.durationMs,
@@ -40829,11 +40906,11 @@ Examples:
40829
40906
  $ qawolf runner keepalive
40830
40907
  $ qawolf runner keepalive --runner ci`;
40831
40908
  function registerRunnerLifecycleCommands(runner, signals) {
40832
- declareCommandKind(runner.command("launch"), "write").description("Launch an interactive runner and make it this directory's default").option("--id <id>", "Id to launch under. Relaunching an id attaches to that runner").option("--name <family>", "Runner family to run, e.g. playwright").addHelpText("after", launchExamples).addHelpText("after", runnerGuides.launch).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerLaunch(ctx, { id: opts.id, name: opts.name }, runnerDeps(ctx)))(opts, command));
40833
- declareCommandKind(runner.command("list"), "read").description("List the runners running on your team").option("--here", "Only the runners this directory launched or QAWOLF_RUNNER_ID names").addHelpText("after", listExamples2).addHelpText("after", runnerGuides.list).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerList(ctx, { here: opts.here === true }, runnerDeps(ctx)))(opts, command));
40834
- declareCommandKind(runner.command("terminate"), "write").description("End an interactive runner, and the pod it runs on with it").option("--runner <id>", runnerFlagDescription).addHelpText("after", runnerGuides.stopOrTerminate).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerTerminate(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
40835
- declareCommandKind(runner.command("stop-run"), "write").description("Stop what a runner is currently executing, leaving the runner up").option("--runner <id>", runnerFlagDescription).addHelpText("after", runnerGuides.stopOrTerminate).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerStopRun(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
40836
- declareCommandKind(runner.command("keepalive"), "read").description("Reset a runner's inactivity clock, for a caller that pauses between actions").option("--runner <id>", runnerFlagDescription).addHelpText("after", keepaliveExamples).addHelpText("after", runnerGuides.keepalive).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerKeepalive(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
40909
+ declareCommandKind(runner.command("launch"), "write").description("Launch an interactive runner and make it this directory's default").option("--id <id>", "Id to launch under. Relaunching an id attaches to that runner").option("--name <family>", "Runner family to run, e.g. playwright").addHelpText("after", launchExamples).addHelpText("after", runnerGuides.launch).action((opts, command) => withRunnerContext(signals, (ctx) => handleRunnerLaunch(ctx, { id: opts.id, name: opts.name }, runnerDeps(ctx)))(opts, command));
40910
+ declareCommandKind(runner.command("list"), "read").description("List the runners running on your team").option("--here", "Only the runners this directory launched or QAWOLF_RUNNER_ID names").addHelpText("after", listExamples2).addHelpText("after", runnerGuides.list).action((opts, command) => withRunnerContext(signals, (ctx) => handleRunnerList(ctx, { here: opts.here === true }, runnerDeps(ctx)))(opts, command));
40911
+ declareCommandKind(runner.command("terminate"), "write").description("End an interactive runner, and the pod it runs on with it").option("--runner <id>", runnerFlagDescription).addHelpText("after", runnerGuides.stopOrTerminate).action((opts, command) => withRunnerContext(signals, (ctx) => handleRunnerTerminate(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
40912
+ declareCommandKind(runner.command("stop-run"), "write").description("Stop what a runner is currently executing, leaving the runner up").option("--runner <id>", runnerFlagDescription).addHelpText("after", runnerGuides.stopOrTerminate).action((opts, command) => withRunnerContext(signals, (ctx) => handleRunnerStopRun(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
40913
+ declareCommandKind(runner.command("keepalive"), "read").description("Reset a runner's inactivity clock, for a caller that pauses between actions").option("--runner <id>", runnerFlagDescription).addHelpText("after", keepaliveExamples).addHelpText("after", runnerGuides.keepalive).action((opts, command) => withRunnerContext(signals, (ctx) => handleRunnerKeepalive(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
40837
40914
  }
40838
40915
 
40839
40916
  // src/domains/interactiveRunner/promoteSnapshot.ts
@@ -40890,7 +40967,7 @@ Examples:
40890
40967
  $ qawolf runner promote-snapshot --screenshot checkout-1-actual.png --baseline checkout-1.png
40891
40968
  $ qawolf runner events run-events --tail 20 | jq 'select(.type == "imageDiffArtifact")'`;
40892
40969
  function registerRunnerPromoteSnapshotCommand(runner, signals) {
40893
- declareCommandKind(runner.command("promote-snapshot"), "write").description("Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it").requiredOption("--screenshot <path>", "The screenshot to promote, as the image diff named it").requiredOption("--baseline <path>", "The baseline to replace, as the image diff named it").option("--runner <id>", runnerFlagDescription).addHelpText("after", promoteSnapshotExamples).addHelpText("after", runnerGuides.promoteSnapshot).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerPromoteSnapshot(ctx, {
40970
+ declareCommandKind(runner.command("promote-snapshot"), "write").description("Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it").requiredOption("--screenshot <path>", "The screenshot to promote, as the image diff named it").requiredOption("--baseline <path>", "The baseline to replace, as the image diff named it").option("--runner <id>", runnerFlagDescription).addHelpText("after", promoteSnapshotExamples).addHelpText("after", runnerGuides.promoteSnapshot).action((opts, command) => withRunnerContext(signals, (ctx) => handleRunnerPromoteSnapshot(ctx, {
40894
40971
  baselinePath: opts.baseline,
40895
40972
  runner: opts.runner,
40896
40973
  screenshotPath: opts.screenshot
@@ -41084,7 +41161,7 @@ Examples:
41084
41161
  $ qawolf runner events run-logs --run <runId> --follow
41085
41162
  $ qawolf runner events console --since 120 --json`;
41086
41163
  function registerRunnerEventsCommand(runner, signals) {
41087
- declareCommandKind(runner.command("events <stream>"), "read").description(`Print a runner's journal, one entry per line. QA Wolf writes ${knownJournalStreams.join(", ")}`).option("--follow", "Keep reading as new entries arrive. Reading counts as activity, so a follow left open keeps the runner alive and billing", false).option("--run <id>", "Restrict run-scoped streams to one run").option("--runner <id>", runnerFlagDescription).option("--since <sequence>", "Read entries after this sequence").option("--tail <count>", "Read only the newest <count> entries").option("--timeout <seconds>", "Give up following after this long. Reading keeps the runner alive, so a follow left open would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", eventsExamples).addHelpText("after", runnerGuides.events).action((stream, opts, command) => withAuthContext(signals, (ctx) => handleRunnerEvents(ctx, {
41164
+ declareCommandKind(runner.command("events <stream>"), "read").description(`Print a runner's journal, one entry per line. QA Wolf writes ${knownJournalStreams.join(", ")}`).option("--follow", "Keep reading as new entries arrive. Reading counts as activity, so a follow left open keeps the runner alive and billing", false).option("--run <id>", "Restrict run-scoped streams to one run").option("--runner <id>", runnerFlagDescription).option("--since <sequence>", "Read entries after this sequence").option("--tail <count>", "Read only the newest <count> entries").option("--timeout <seconds>", "Give up following after this long. Reading keeps the runner alive, so a follow left open would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", eventsExamples).addHelpText("after", runnerGuides.events).action((stream, opts, command) => withRunnerContext(signals, (ctx) => handleRunnerEvents(ctx, {
41088
41165
  envelope: Boolean(command.optsWithGlobals().json),
41089
41166
  follow: opts.follow,
41090
41167
  run: opts.run,
@@ -41405,8 +41482,12 @@ async function sendRunFlowRequest(ctx, options, delta) {
41405
41482
  ...delta.unchangedFiles === undefined ? {} : { unchangedFiles: delta.unchangedFiles }
41406
41483
  }, runnerCallOptions);
41407
41484
  if (!result.ok) {
41485
+ const failure = runnerRequestFailure(result, options.resolved);
41408
41486
  return {
41409
- failure: runnerRequestFailure(result, options.resolved),
41487
+ failure: result.mayHaveArrived ? {
41488
+ ...failure,
41489
+ error: appendSentence(failure.error, interactiveRunnerMessages.submitLostMayHaveStarted)
41490
+ } : failure,
41410
41491
  type: "failed"
41411
41492
  };
41412
41493
  }
@@ -41554,7 +41635,7 @@ Examples:
41554
41635
  $ qawolf runner run flows/checkout.flow.ts --lines 4-9 --lines-file pages/login.ts
41555
41636
  $ qawolf runner run flows/checkout.flow.ts --env-id staging`;
41556
41637
  function registerRunCommand(runner, signals) {
41557
- declareCommandKind(runner.command("run <flowFile>"), "write").description("Run a flow on an interactive runner, shipping the flow and what it imports").option("--follow", "Report the run's status until it settles: in progress, then passed or failed", false).option("--logs", "Stream every log line the run produces while following. Implies --follow", false).option("--run-events", "Stream the run's progress events as JSON lines while following. Implies --follow", false).option("--recorder-events", "Stream the browser actions the runner records as JSON lines while following, from an anchor taken just before submission: the recorder is runner-wide, not run-scoped. Implies --follow", false).option("--env-id <env>", "QA Wolf environment whose variables the run is given, by id or alias. Defaults to QAWOLF_ENVIRONMENT. QA Wolf reads and decrypts them itself, so they never leave the server and no size limit applies to them").option("--env-file <path>", "Dotenv file on this machine whose variables the run is given. Pass this or --env-id, not both").option("--lines <start-end>", "Run only these 1-indexed lines against the browser as it stands, instead of the whole flow from a fresh one").option("--lines-file <path>", "File the --lines range lives in. Defaults to <flowFile>; pass it only when the lines are in another file, such as a page object").option("--runner <id>", runnerFlagDescription).option("--timeout <seconds>", "Give up following after this long. Following keeps the runner alive, so a run that never settles would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", runExamples2).addHelpText("after", runnerGuides.run).action((flowFile, opts, command) => withAuthContext(signals, (ctx) => handleRunnerRun(ctx, {
41638
+ declareCommandKind(runner.command("run <flowFile>"), "write").description("Run a flow on an interactive runner, shipping the flow and what it imports").option("--follow", "Report the run's status until it settles: in progress, then passed or failed", false).option("--logs", "Stream every log line the run produces while following. Implies --follow", false).option("--run-events", "Stream the run's progress events as JSON lines while following. Implies --follow", false).option("--recorder-events", "Stream the browser actions the runner records as JSON lines while following, from an anchor taken just before submission: the recorder is runner-wide, not run-scoped. Implies --follow", false).option("--env-id <env>", "QA Wolf environment whose variables the run is given, by id or alias. Defaults to QAWOLF_ENVIRONMENT. QA Wolf reads and decrypts them itself, so they never leave the server and no size limit applies to them").option("--env-file <path>", "Dotenv file on this machine whose variables the run is given. Pass this or --env-id, not both").option("--lines <start-end>", "Run only these 1-indexed lines against the browser as it stands, instead of the whole flow from a fresh one").option("--lines-file <path>", "File the --lines range lives in. Defaults to <flowFile>; pass it only when the lines are in another file, such as a page object").option("--runner <id>", runnerFlagDescription).option("--timeout <seconds>", "Give up following after this long. Following keeps the runner alive, so a run that never settles would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", runExamples2).addHelpText("after", runnerGuides.run).action((flowFile, opts, command) => withRunnerContext(signals, (ctx) => handleRunnerRun(ctx, {
41558
41639
  entryPoint: flowFile,
41559
41640
  envFile: opts.envFile,
41560
41641
  envId: opts.envId,
@@ -41572,7 +41653,8 @@ function registerRunCommand(runner, signals) {
41572
41653
  // src/core/messages/interactiveRunner/recording.ts
41573
41654
  var recordingMessages = {
41574
41655
  noRunnerIdForHistory: "Name the runner whose recordings to read with --runner <id> or QAWOLF_RUNNER_ID. History stays readable after the runner terminates.",
41575
- unsupported: "Video recording requires a Playwright runner.",
41656
+ unsupported: "This runner has no screen to record. Launch a browser, mobile, Windows, or Mac runner instead.",
41657
+ screenNotReady: "The runner's screen is not ready to record yet. On a browser runner, retry in a second or two. On a mobile, Windows, or Mac runner, a run must claim the device first. Run code on it, or turn on runner record auto before the next full run.",
41576
41658
  inProgress: "A recording is already in progress. Use runner record status to check its mode and id. Stop a manual recording by id, or wait for the run to finish an automatic recording.",
41577
41659
  notFound: "That recording was not found on the runner. Use runner record status for the active recording or runner list-recordings for published history.",
41578
41660
  idUsed: "That recording id has already been used. Start a new recording with a new UUID.",
@@ -41591,7 +41673,7 @@ function recordingFailure(reason) {
41591
41673
  };
41592
41674
  case "screen-not-ready":
41593
41675
  return {
41594
- error: interactiveRunnerMessages.screenNotReady,
41676
+ error: recordingMessages.screenNotReady,
41595
41677
  exitCode: exitCodes.network
41596
41678
  };
41597
41679
  case "recording-in-progress":
@@ -41743,27 +41825,27 @@ async function handleRunnerRecordings(ctx, options, deps) {
41743
41825
 
41744
41826
  // src/commands/runner/recording.register.ts
41745
41827
  function registerRunnerRecordingCommands(runner, signals) {
41746
- const record = runner.command("record").description("Control video recording on a Playwright runner").addHelpText("after", runnerGuides.record);
41747
- declareCommandKind(record.command("start"), "write").description("Start manual video capture across runs. Requires a ready screen and suppresses automatic capture until stopped").option("--recording-id <uuid>", "Recording UUID. Generated when omitted; reuse it when retrying this start").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecord(ctx, {
41828
+ const record = runner.command("record").description("Control video recording on a browser, mobile, Windows, or Mac runner").addHelpText("after", runnerGuides.record);
41829
+ declareCommandKind(record.command("start"), "write").description("Start manual video capture across runs. Requires a ready screen and suppresses automatic capture until stopped").option("--recording-id <uuid>", "Recording UUID. Generated when omitted; reuse it when retrying this start").option("--runner <id>", runnerFlagDescription).action((opts, command) => withRunnerContext(signals, (ctx) => handleRunnerRecord(ctx, {
41748
41830
  command: { action: "start", recordingId: opts.recordingId },
41749
41831
  runner: opts.runner
41750
41832
  }, runnerDeps(ctx)))(opts, command));
41751
- declareCommandKind(record.command("stop <recording-id>"), "write").description("Stop the recording with this UUID and publish it. Retrying cannot stop a later recording").option("--runner <id>", runnerFlagDescription).action((recordingId, opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecord(ctx, {
41833
+ declareCommandKind(record.command("stop <recording-id>"), "write").description("Stop the recording with this UUID and publish it. Retrying cannot stop a later recording").option("--runner <id>", runnerFlagDescription).action((recordingId, opts, command) => withRunnerContext(signals, (ctx) => handleRunnerRecord(ctx, {
41752
41834
  command: { action: "stop", recordingId },
41753
41835
  runner: opts.runner
41754
41836
  }, runnerDeps(ctx)))(opts, command));
41755
- declareCommandKind(record.command("status"), "read").description("Show the active recording and automatic recording setting").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecord(ctx, {
41837
+ declareCommandKind(record.command("status"), "read").description("Show the active recording and automatic recording setting").option("--runner <id>", runnerFlagDescription).action((opts, command) => withRunnerContext(signals, (ctx) => handleRunnerRecord(ctx, {
41756
41838
  command: { action: "status" },
41757
41839
  runner: opts.runner
41758
41840
  }, runnerDeps(ctx)))(opts, command));
41759
41841
  declareCommandKind(record.command("auto"), "write").addArgument(new Argument2("<setting>", "Automatic recording setting").choices([
41760
41842
  "on",
41761
41843
  "off"
41762
- ])).description("Enable or disable automatic recording for subsequent full runs").option("--runner <id>", runnerFlagDescription).action((setting, opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecord(ctx, {
41844
+ ])).description("Enable or disable automatic recording for subsequent full runs").option("--runner <id>", runnerFlagDescription).action((setting, opts, command) => withRunnerContext(signals, (ctx) => handleRunnerRecord(ctx, {
41763
41845
  command: { action: "auto", enabled: setting === "on" },
41764
41846
  runner: opts.runner
41765
41847
  }, runnerDeps(ctx)))(opts, command));
41766
- declareCommandKind(runner.command("list-recordings"), "read").description("Read a page of published video recordings, including after the runner terminates. Platform URLs persist; video URLs expire").option("--runner <id>", runnerFlagDescription).option("--recording-id <uuid>", "Look up one recording; an empty result means it is not published or does not exist").option("--page-token <token>", "Continue from nextPageToken returned by the previous page").addHelpText("after", runnerGuides.listRecordings).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecordings(ctx, {
41848
+ declareCommandKind(runner.command("list-recordings"), "read").description("Read a page of published video recordings, including after the runner terminates. Platform URLs persist; video URLs expire").option("--runner <id>", runnerFlagDescription).option("--recording-id <uuid>", "Look up one recording; an empty result means it is not published or does not exist").option("--page-token <token>", "Continue from nextPageToken returned by the previous page").addHelpText("after", runnerGuides.listRecordings).action((opts, command) => withRunnerContext(signals, (ctx) => handleRunnerRecordings(ctx, {
41767
41849
  runner: opts.runner,
41768
41850
  ...opts.recordingId === undefined ? {} : { recordingId: opts.recordingId },
41769
41851
  ...opts.pageToken === undefined ? {} : { pageToken: opts.pageToken }
@@ -41772,7 +41854,7 @@ function registerRunnerRecordingCommands(runner, signals) {
41772
41854
 
41773
41855
  // src/commands/runner/index.ts
41774
41856
  function registerRunnerCommand(program, signals) {
41775
- const runner = declareReferenceGuide(program.command("runner"), runnerWorkflowGuide).description("Drive an interactive runner on the QA Wolf platform");
41857
+ const runner = declareReferenceGuide(program.command("runner"), runnerWorkflowGuide).description("Drive an interactive runner on the QA Wolf platform").addOption(workspaceIdOption()).configureHelp({ showGlobalOptions: true });
41776
41858
  registerRunnerLifecycleCommands(runner, signals);
41777
41859
  registerRunCommand(runner, signals);
41778
41860
  registerRunnerEventsCommand(runner, signals);
@@ -41816,4 +41898,4 @@ createProgram({ signals }).parseAsync().catch(() => {
41816
41898
  process.exitCode = 1;
41817
41899
  }).finally(() => exitWhenIdle(typeof process.exitCode === "number" ? process.exitCode : 0));
41818
41900
 
41819
- //# debugId=F8E2C24048CC67D764756E2164756E21
41901
+ //# debugId=EE62A061E9D077A764756E2164756E21