@qawolf/cli 2.2.0 → 2.2.2

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
@@ -8440,6 +8440,7 @@ var authErrorMessages = {
8440
8440
  rejected401: (noun) => `QA Wolf API rejected the${noun ? ` ${noun}` : ""} request (HTTP 401). Check your API key.`,
8441
8441
  rejected402: (noun) => `QA Wolf API refused the${noun ? ` ${noun}` : ""} request (HTTP 402): billing prevented it.`,
8442
8442
  rejected403: (noun) => `QA Wolf API rejected the${noun ? ` ${noun}` : ""} request (HTTP 403). Check that your API key has access to this environment.`,
8443
+ blocked403: (noun) => `The${noun ? ` ${noun}` : ""} request was blocked before it reached the QA Wolf API (HTTP 403), so your API key was not checked.`,
8443
8444
  notFound404Environment: (noun) => `QA Wolf API could not find ${noun ? `${noun} for that environment` : "that environment"} (HTTP 404). Check the --env value.`,
8444
8445
  notFound404Runner: (runnerId) => runnerId === undefined ? "That runner is not running (HTTP 404)." : `Runner ${runnerId} is not running (HTTP 404).`,
8445
8446
  runnerIsGone: "It was never launched, or it has since been terminated or idled out.",
@@ -8449,7 +8450,7 @@ var authErrorMessages = {
8449
8450
  notFound404Record: (noun, id) => `QA Wolf has no ${noun} ${id} (HTTP 404).`,
8450
8451
  notFound404: (noun) => noun === undefined ? "QA Wolf found nothing matching the request (HTTP 404)." : `QA Wolf found nothing matching the ${noun} request (HTTP 404).`,
8451
8452
  failedWithStatus: (status, noun) => `QA Wolf API${noun ? ` ${noun}` : ""} request failed (HTTP ${status}).`,
8452
- 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
+ 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.`,
8453
8454
  timedOut: (timeoutMs, noun) => `The QA Wolf API${noun ? ` ${noun}` : ""} request timed out after ${formatSeconds(timeoutMs)}. The work may still be finishing on the platform.`,
8454
8455
  unexpectedResponse: (noun) => `Unexpected${noun ? ` ${noun}` : ""} response from the QA Wolf API.`
8455
8456
  },
@@ -8935,10 +8936,10 @@ var lifecycleMessages = {
8935
8936
  launched: (id, url) => `Launched runner ${id}. ${pageAt(url)}`,
8936
8937
  launchedForCommand: (id, url) => `No runner was given, so launched ${id} for this command. Its browser is fresh: nothing has been run on it and nothing is signed in. It bills until it is terminated or idles out, so terminate it with qawolf runner terminate --runner ${id} when you are done. ${pageAt(url)}`,
8937
8938
  noRunnerIdForImport: `${noRunnerId} An install also needs a live run to go into, which a runner gets from qawolf runner run.`,
8938
- noRunnerIdForHighlight: `${noRunnerId} Highlighting also needs a live page to draw on, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
8939
- noRunnerIdForInspect: `${noRunnerId} Inspecting also needs a page, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
8939
+ noRunnerIdForHighlight: `${noRunnerId} A playwright runner has a page to draw on as soon as it launches.`,
8940
+ noRunnerIdForInspect: `${noRunnerId} A playwright runner can be inspected as soon as it launches, and any other runner once a flow has run on it with qawolf runner run.`,
8940
8941
  noRunnerIdForPromoteSnapshot: `${noRunnerId} A baseline is replaced on the runner that produced the screenshot, so it has to be the runner the diff came from.`,
8941
- noRunnerIdForScreenshot: `${noRunnerId} A screenshot also needs a screen, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
8942
+ noRunnerIdForScreenshot: `${noRunnerId} A playwright runner has a screen as soon as it launches, and any other runner once a flow has run on it with qawolf runner run.`,
8942
8943
  noRunnerId,
8943
8944
  wasNotRunning: (id) => `Runner ${id} was not running.`,
8944
8945
  terminated: (id) => `Terminated runner ${id}.`,
@@ -8993,6 +8994,7 @@ var runMessages = {
8993
8994
  unknownStream: (stream, known) => `"${stream}" is not a stream QA Wolf writes, so this read has nothing to return. QA Wolf writes ${known.join(", ")}.`,
8994
8995
  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.`,
8995
8996
  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.",
8997
+ 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.",
8996
8998
  targetMismatch: (runnerName, requiredRunnerName) => `This flow needs a ${requiredRunnerName} runner and ${runnerName} is running. Launch one with --name ${requiredRunnerName}.`
8997
8999
  };
8998
9000
 
@@ -15446,6 +15448,46 @@ function applyWorkspaceId(inputSchema, input, workspaceId) {
15446
15448
  return { ...input, workspaceId };
15447
15449
  }
15448
15450
 
15451
+ // src/core/fetchCause.ts
15452
+ var maxCauseDepth = 5;
15453
+ var maxCauseMessageLength = 120;
15454
+ var codePattern = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
15455
+ var urlPattern = /\bhttps?:\/\/\S+/g;
15456
+ function causeChain(options) {
15457
+ const { error, remainingDepth } = options;
15458
+ const { cause } = error;
15459
+ if (!(cause instanceof Error) || remainingDepth === 0)
15460
+ return [error];
15461
+ return [
15462
+ error,
15463
+ ...causeChain({ error: cause, remainingDepth: remainingDepth - 1 })
15464
+ ];
15465
+ }
15466
+ function shortMessage(message) {
15467
+ const withoutUrls = message.replace(urlPattern, "<url>").trim();
15468
+ return withoutUrls.length > maxCauseMessageLength ? `${withoutUrls.slice(0, maxCauseMessageLength)}…` : withoutUrls;
15469
+ }
15470
+ function describeFetchCause(error) {
15471
+ const chain = causeChain({ error, remainingDepth: maxCauseDepth });
15472
+ const root = chain.at(-1);
15473
+ const code = chain.map((link) => errorCode(link)).reverse().find((candidate) => candidate !== undefined && codePattern.test(candidate));
15474
+ const message = root === undefined ? "" : shortMessage(root.message);
15475
+ if (code === undefined)
15476
+ return message || undefined;
15477
+ if (!message || message.includes(code))
15478
+ return message || code;
15479
+ return `${code}: ${message}`;
15480
+ }
15481
+
15482
+ // src/core/parseJson.ts
15483
+ function parseJson(text) {
15484
+ try {
15485
+ return JSON.parse(text);
15486
+ } catch {
15487
+ return;
15488
+ }
15489
+ }
15490
+
15449
15491
  // src/shell/platform/describeNotFound.ts
15450
15492
  var m = authMessages.errors.request;
15451
15493
  var saysNothingMore = (reason) => /^(\w+ )*not ?found\.?$/i.test(reason.trim());
@@ -15563,13 +15605,19 @@ function describeRequestError(err, baseUrl, noun, notFound) {
15563
15605
  ...body
15564
15606
  };
15565
15607
  if (err.status === 403)
15566
- return { error: m2.request.rejected403(noun), ...body };
15608
+ return parseJson(err.body) === undefined ? { error: m2.request.blocked403(noun) } : { error: m2.request.rejected403(noun), ...body };
15567
15609
  if (err.status === 404)
15568
15610
  return describeNotFound(notFound, noun, reason);
15569
15611
  return { error: m2.request.failedWithStatus(err.status, noun), ...body };
15570
15612
  }
15571
15613
  if (err.kind === "network") {
15572
- return { error: m2.request.networkUnreachable(baseUrl, noun) };
15614
+ return {
15615
+ error: m2.request.networkUnreachable({
15616
+ baseUrl,
15617
+ cause: describeFetchCause(err.cause),
15618
+ noun
15619
+ })
15620
+ };
15573
15621
  }
15574
15622
  if (err.kind === "timeout") {
15575
15623
  return { error: m2.request.timedOut(err.timeoutMs, noun) };
@@ -23624,7 +23672,7 @@ function startUpdateCheck(deps) {
23624
23672
  // package.json
23625
23673
  var package_default = {
23626
23674
  name: "@qawolf/cli",
23627
- version: "2.2.0",
23675
+ version: "2.2.2",
23628
23676
  description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
23629
23677
  keywords: [
23630
23678
  "automation",
@@ -24206,15 +24254,6 @@ async function handleAgentGet(ctx, options, deps) {
24206
24254
  // src/shell/agent/sessionStore.ts
24207
24255
  import { join as join14 } from "node:path";
24208
24256
 
24209
- // src/core/parseJson.ts
24210
- function parseJson(text) {
24211
- try {
24212
- return JSON.parse(text);
24213
- } catch {
24214
- return;
24215
- }
24216
- }
24217
-
24218
24257
  // src/shell/jsonFile.ts
24219
24258
  var pendingWrites = 0;
24220
24259
  async function readJsonFile(fs, path, schema) {
@@ -38813,6 +38852,9 @@ function buildRunnerAction(type, flags) {
38813
38852
  if (to !== undefined && !to.ok)
38814
38853
  return to;
38815
38854
  const button = flags.button ?? (type === "click" ? "left" : undefined);
38855
+ const scrollsOneWay = type === "scroll" && flags.scrollX === undefined !== (flags.scrollY === undefined);
38856
+ const scrollX = flags.scrollX ?? (scrollsOneWay ? "0" : undefined);
38857
+ const scrollY = flags.scrollY ?? (scrollsOneWay ? "0" : undefined);
38816
38858
  const candidate = {
38817
38859
  type,
38818
38860
  ...button === undefined ? {} : { button },
@@ -38820,8 +38862,8 @@ function buildRunnerAction(type, flags) {
38820
38862
  ...from === undefined ? {} : { from: from.value },
38821
38863
  ...flags.keys === undefined ? {} : { keys: flags.keys },
38822
38864
  ...parsedPath === undefined ? {} : { path: parsedPath.value },
38823
- ...flags.scrollX === undefined ? {} : { scroll_x: toNumber(flags.scrollX) },
38824
- ...flags.scrollY === undefined ? {} : { scroll_y: toNumber(flags.scrollY) },
38865
+ ...scrollX === undefined ? {} : { scroll_x: toNumber(scrollX) },
38866
+ ...scrollY === undefined ? {} : { scroll_y: toNumber(scrollY) },
38825
38867
  ...flags.selector === undefined ? {} : { selector: flags.selector },
38826
38868
  ...flags.strategy === undefined ? {} : { strategy: flags.strategy },
38827
38869
  ...flags.text === undefined ? {} : { text: flags.text },
@@ -39397,7 +39439,7 @@ On mobile, send tap and swipe, never click or drag. The other browser actions, d
39397
39439
 
39398
39440
  # Before the first run
39399
39441
 
39400
- A runner has no screen until its first run, so act exits 2 until then, except navigate, which exits 1 (action-failed): it skips the screen but still needs the runner to have run something. With no runner named at all, act launches one and says so on stderr.
39442
+ A playwright runner's screen starts as it launches, so act works on it before anything has run. Any other runner has no screen until its first run, so act exits 2 on it until then. With no runner named at all, act launches one and says so on stderr.
39401
39443
  `;
39402
39444
 
39403
39445
  // src/commands/runner/guides/actions.txt
@@ -39444,7 +39486,7 @@ History is not unbounded: a size cap drops the oldest entries on a long-lived ru
39444
39486
  $ qawolf runner events recorder --tail 5 | jq -r '.code // .type'
39445
39487
  $ qawolf runner events recorder --tail 5 | jq -r '[.locator] + (.alternates // []) | @tsv'
39446
39488
 
39447
- \`code\` is absent on events with no call of their own, such as a navigation, which is why the first line falls back to \`type\`. Use these to turn a session you drove by pixel coordinates into durable selectors, and to check that a click landed on the element you meant rather than near it. The stream is empty until the runner's first run gives it a browser context, so an early empty answer means "not yet", not "broken". Do not add --json here: it wraps each line in an envelope and these field paths stop matching.
39489
+ \`code\` is absent on events with no call of their own, such as a navigation, which is why the first line falls back to \`type\`. Use these to turn a session you drove by pixel coordinates into durable selectors, and to check that a click landed on the element you meant rather than near it. The stream stays empty while a playwright runner still shows its welcome page, and on any other runner until its first run, so an early empty answer means "not yet", not "broken". Do not add --json here: it wraps each line in an envelope and these field paths stop matching.
39448
39490
 
39449
39491
  # Following
39450
39492
 
@@ -39471,7 +39513,7 @@ The snippet imports nothing of yours by default. Pass --file <path> to evaluate
39471
39513
 
39472
39514
  # Failures
39473
39515
 
39474
- exec exits 2 until the runner's first run, since there is no page to evaluate against. On a 4 the message says the snippet could not be evaluated, but a lost answer looks the same from outside, so treat a 4 from a snippet that changes something as "may have run" rather than "did not run", and check its effect before running it again. With no runner named at all, exec launches one and says so on stderr.
39516
+ A playwright runner has a page to evaluate against as soon as it launches. On a 4 the message says the snippet could not be evaluated, but a lost answer looks the same from outside, so treat a 4 from a snippet that changes something as "may have run" rather than "did not run", and check its effect before running it again. With no runner named at all, exec launches one and says so on stderr.
39475
39517
  `;
39476
39518
 
39477
39519
  // src/commands/runner/guides/formatGuide.ts
@@ -39558,27 +39600,12 @@ It is a read with a cost: keeping the clock reset keeps a billed pod alive. Call
39558
39600
  `;
39559
39601
 
39560
39602
  // src/commands/runner/guides/launch.txt
39561
- var launch_default = `# Ids
39562
-
39563
- Runner ids are yours to choose and are scoped to your team, so agent-1 is a fine id. Launching an id that is already running attaches to that runner instead of starting and billing a second one, and the answer says which happened: read \`alreadyRunning\`. Reusing one id is therefore the cheap and safe pattern. The same id with a different --name is refused rather than silently ignored.
39564
-
39565
- launch takes its id from --id and never reads QAWOLF_RUNNER_ID. A bare \`qawolf runner launch\` invents a random id, bills a pod under it and stores it, so a harness that exported the variable and then launched without --id ends up with a pod it is not addressing. Pass --id whenever you have an id in mind.
39566
-
39567
- Launching an id that differs from QAWOLF_RUNNER_ID prints a warning on stderr naming both ids: the variable still outranks the directory default, so commands that omit --runner keep going to whatever it names, not the runner you just launched. That is expected when you launch an additional runner on purpose. Address that one with --runner rather than re-exporting the variable, which would repoint every other runner-less command too.
39568
-
39569
- # The page
39570
-
39571
- Either answer carries a \`url\`, which launch prints, as does a command that launched its own runner. It is a QA Wolf page showing what the runner is doing, where a person can also take over with their own mouse and keyboard. Hand it to a person who asks what your runner is up to. The page opens for anyone on the runner's team, however the runner was launched. There is nothing to see until the runner's first run starts its screen, so the page waits until then. You read the screen with \`screenshot\`, not with the page.
39572
-
39573
- # Browser or mobile
39574
-
39575
- --name also chooses between a browser and a mobile device: --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 and elements on a browser runner, and runner-is-not-a-browser from inspect element-html and page-html on a mobile one. Launch the right family up front rather than discovering it from a refusal mid-session.
39576
- `;
39603
+ var launch_default = "# Ids\n\nRunner ids are yours to choose and are scoped to your team, so agent-1 is a fine id. Launching an id that is already running attaches to that runner instead of starting and billing a second one, and the answer says which happened: read `alreadyRunning`. Reusing one id is therefore the cheap and safe pattern. --name does not change a runner that is already running: the answer's `runnerName` says what you attached to.\n\nlaunch takes its id from --id and never reads QAWOLF_RUNNER_ID. A bare `qawolf runner launch` invents a random id, bills a pod under it and stores it, so a harness that exported the variable and then launched without --id ends up with a pod it is not addressing. Pass --id whenever you have an id in mind.\n\nLaunching an id that differs from QAWOLF_RUNNER_ID prints a warning on stderr naming both ids: the variable still outranks the directory default, so commands that omit --runner keep going to whatever it names, not the runner you just launched. That is expected when you launch an additional runner on purpose. Address that one with --runner rather than re-exporting the variable, which would repoint every other runner-less command too.\n\n# The page\n\nEither answer carries a `url`, which launch prints, as does a command that launched its own runner. It is a QA Wolf page showing what the runner is doing, where a person can also take over with their own mouse and keyboard. Hand it to a person who asks what your runner is up to. The page opens for anyone on the runner's team, however the runner was launched. A playwright runner's screen starts as it launches, showing a QA Wolf welcome page. Any other runner's screen starts with its first run, so its page waits until then. You read the screen with `screenshot`, not with the page.\n\n# Browser or mobile\n\n--name also chooses between a browser and a mobile device: --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 and elements on a browser runner, and runner-is-not-a-browser from inspect element-html and page-html on a mobile one. Launch the right family up front rather than discovering it from a refusal mid-session.\n";
39577
39604
 
39578
39605
  // src/commands/runner/guides/list.txt
39579
39606
  var list_default = `# What the list holds
39580
39607
 
39581
- The list names the runners this directory has launched that are still running, and marks the one a command with no --runner would reach. It also includes the runner named by QAWOLF_RUNNER_ID even though this directory did not launch it, so a harness handed a runner sees it alongside the ones it started itself. Use the id column with --runner to address any of them; addressing one does not make it the default.
39608
+ The list names every active runner on your team, marking the ones this directory launched and the default, the one a command with no --runner would reach. --here keeps only this directory's runners and the one QAWOLF_RUNNER_ID names. Use the id column with --runner to address any of them; addressing one does not make it the default.
39582
39609
 
39583
39610
  Every runner is looked up before it is listed, so a runner that idled out is absent rather than reported. The lookup neither starts a runner nor resets an inactivity clock, which is what separates list from keepalive: listing tells you what is there and changes nothing. A lookup that cannot be answered fails the command rather than returning a shorter list, because a short list reads as the whole truth.
39584
39611
 
@@ -39669,7 +39696,7 @@ var screenshot_default = `# Reading the screen
39669
39696
 
39670
39697
  The image is a real JPEG on disk, decoded, because every coding harness can open an image file. Read it with whatever vision you have. --out - writes the JPEG bytes to stdout instead, on their own, for a caller that is a process rather than an agent: the confirmation, and the JSON line under --json, goes to stderr so nothing follows the image on stdout. A terminal on stdout is refused: redirect or pipe it.
39671
39698
 
39672
- A runner has no screen until its first run, so until then screenshot exits 2. It never launches a runner. When you are about to act anyway, \`act --screenshot\` performs the action and returns the screen in one call.
39699
+ A playwright runner's screen starts as it launches. Any other runner has no screen until its first run, so until then screenshot exits 2 on it. It never launches a runner. When you are about to act anyway, \`act --screenshot\` performs the action and returns the screen in one call.
39673
39700
  `;
39674
39701
 
39675
39702
  // src/commands/runner/guides/stopOrTerminate.txt
@@ -39683,7 +39710,7 @@ Both succeed when there was nothing to do, and say which: \`wasRunning\` is fals
39683
39710
  `;
39684
39711
 
39685
39712
  // src/commands/runner/guides/workflow.md
39686
- 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` and `exec`. Read that announcement. The browser it just started is fresh: nothing has been run on it, nothing is signed in, and no page is open. 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 freshly launched runner has no screen. The virtual desktop starts with the runner's first run and nothing else starts it, so until you have run something:\n\n- `screenshot` and `act` fail with exit code `2`, except `navigate`, which fails with exit code `1` (`action-failed`): it skips the screen but still needs the runner to have run something\n- `exec` fails with exit code `2`\n- `events recorder` reads as empty\n\nNone of that is a fault, and none of it clears on its own. Only `qawolf runner run <flow>` starts the screen. A bare navigate does not: it fails until the first run, however long you wait.\n\nSo the first thing you do to a new runner has to put a browser on it. That means a flow file and a `package.json` on disk, even if all you want is to drive the browser by hand; there is no \"just give me a screen\" call. Once one run has happened, the screenshot-and-act loop works for the rest of the runner's life. A `--lines` selection is the one call that does not need a run first.\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 is up but cannot serve this instant: 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- `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`. The run is what starts the screen, so it is not optional even though the goal here is to drive by hand.\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 # starts the screen; 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";
39713
+ 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";
39687
39714
 
39688
39715
  // src/commands/runner/guides/index.ts
39689
39716
  var runnerGuides = {
@@ -40608,6 +40635,7 @@ Examples:
40608
40635
  $ qawolf runner act click --button left --x 480 --y 260
40609
40636
  $ qawolf runner act type --text "hello@example.com"
40610
40637
  $ qawolf runner act keypress --keys Control a
40638
+ $ qawolf runner act scroll --x 640 --y 400 --scroll-y 600
40611
40639
  $ qawolf runner act navigate --url https://example.com
40612
40640
  $ qawolf runner act drag --path '[{"x":10,"y":20},{"x":80,"y":90}]'
40613
40641
  $ qawolf runner act click --button left --x 480 --y 260 --screenshot step-4.jpg
@@ -40630,7 +40658,7 @@ Examples:
40630
40658
  $ qawolf runner screenshot --out - | my-vision-tool`;
40631
40659
  function registerRunnerInteractCommands(runner, signals) {
40632
40660
  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));
40633
- 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, {
40661
+ 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) => withAuthContext(signals, (ctx) => handleRunnerAct(ctx, {
40634
40662
  flags: {
40635
40663
  button: opts.button,
40636
40664
  durationMs: opts.durationMs,
@@ -40768,7 +40796,7 @@ async function handleRunnerList(ctx, options, deps) {
40768
40796
  if (!listed.ok) {
40769
40797
  return { ...failureFields(listed), exitCode: exitCodes.network };
40770
40798
  }
40771
- const items = options.here ? listed.items.filter((item) => item.launchedHere) : listed.items;
40799
+ const items = options.here ? listed.items.filter((item) => item.launchedHere || item.isDefault) : listed.items;
40772
40800
  if (ctx.ui.mode === "json") {
40773
40801
  ctx.ui.json(items);
40774
40802
  return;
@@ -40844,7 +40872,7 @@ Examples:
40844
40872
  $ qawolf runner keepalive --runner ci`;
40845
40873
  function registerRunnerLifecycleCommands(runner, signals) {
40846
40874
  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));
40847
- declareCommandKind(runner.command("list"), "read").description("List the runners running on your team").option("--here", "Only the runners this directory launched").addHelpText("after", listExamples2).addHelpText("after", runnerGuides.list).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerList(ctx, { here: opts.here === true }, runnerDeps(ctx)))(opts, command));
40875
+ 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));
40848
40876
  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));
40849
40877
  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));
40850
40878
  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));
@@ -41419,8 +41447,12 @@ async function sendRunFlowRequest(ctx, options, delta) {
41419
41447
  ...delta.unchangedFiles === undefined ? {} : { unchangedFiles: delta.unchangedFiles }
41420
41448
  }, runnerCallOptions);
41421
41449
  if (!result.ok) {
41450
+ const failure = runnerRequestFailure(result, options.resolved);
41422
41451
  return {
41423
- failure: runnerRequestFailure(result, options.resolved),
41452
+ failure: result.mayHaveArrived ? {
41453
+ ...failure,
41454
+ error: appendSentence(failure.error, interactiveRunnerMessages.submitLostMayHaveStarted)
41455
+ } : failure,
41424
41456
  type: "failed"
41425
41457
  };
41426
41458
  }
@@ -41586,7 +41618,8 @@ function registerRunCommand(runner, signals) {
41586
41618
  // src/core/messages/interactiveRunner/recording.ts
41587
41619
  var recordingMessages = {
41588
41620
  noRunnerIdForHistory: "Name the runner whose recordings to read with --runner <id> or QAWOLF_RUNNER_ID. History stays readable after the runner terminates.",
41589
- unsupported: "Video recording requires a Playwright runner.",
41621
+ unsupported: "This runner has no screen to record. Launch a browser, mobile, Windows, or Mac runner instead.",
41622
+ 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.",
41590
41623
  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.",
41591
41624
  notFound: "That recording was not found on the runner. Use runner record status for the active recording or runner list-recordings for published history.",
41592
41625
  idUsed: "That recording id has already been used. Start a new recording with a new UUID.",
@@ -41605,7 +41638,7 @@ function recordingFailure(reason) {
41605
41638
  };
41606
41639
  case "screen-not-ready":
41607
41640
  return {
41608
- error: interactiveRunnerMessages.screenNotReady,
41641
+ error: recordingMessages.screenNotReady,
41609
41642
  exitCode: exitCodes.network
41610
41643
  };
41611
41644
  case "recording-in-progress":
@@ -41757,7 +41790,7 @@ async function handleRunnerRecordings(ctx, options, deps) {
41757
41790
 
41758
41791
  // src/commands/runner/recording.register.ts
41759
41792
  function registerRunnerRecordingCommands(runner, signals) {
41760
- const record = runner.command("record").description("Control video recording on a Playwright runner").addHelpText("after", runnerGuides.record);
41793
+ const record = runner.command("record").description("Control video recording on a browser, mobile, Windows, or Mac runner").addHelpText("after", runnerGuides.record);
41761
41794
  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, {
41762
41795
  command: { action: "start", recordingId: opts.recordingId },
41763
41796
  runner: opts.runner
@@ -41830,4 +41863,4 @@ createProgram({ signals }).parseAsync().catch(() => {
41830
41863
  process.exitCode = 1;
41831
41864
  }).finally(() => exitWhenIdle(typeof process.exitCode === "number" ? process.exitCode : 0));
41832
41865
 
41833
- //# debugId=59930438C8ECAB2864756E2164756E21
41866
+ //# debugId=B8D4928E940289A464756E2164756E21
@@ -9507,7 +9507,21 @@ function inspectExecutionLogs(request) {
9507
9507
  }
9508
9508
  function summarizeExecutionLogs(input) {
9509
9509
  const parsed = parseExecutionLogs(input);
9510
- const selected = parsed.items.filter((record) => record.source === "qawolfTraceCollection" || record.severity === "error").slice(-20);
9510
+ const errors = parsed.items.filter((record) => record.severity === "error").slice(-5);
9511
+ const traceCollection = parsed.items.findLast((record) => record.source === "qawolfTraceCollection");
9512
+ const selectedIds = new Set([
9513
+ ...errors.map((record) => record.evidenceId),
9514
+ ...traceCollection ? [traceCollection.evidenceId] : []
9515
+ ]);
9516
+ const selected = parsed.items.filter((record) => selectedIds.has(record.evidenceId));
9517
+ const summaries = selected.map((record) => {
9518
+ const message = redactAndBoundAttemptEvidenceResult(record.message, 1024);
9519
+ return {
9520
+ ...record,
9521
+ message: message.text,
9522
+ ...message.truncated && { evidenceTruncated: true }
9523
+ };
9524
+ });
9511
9525
  return {
9512
9526
  artifactState: parsed.status,
9513
9527
  evidence: {
@@ -9515,9 +9529,9 @@ function summarizeExecutionLogs(input) {
9515
9529
  ...parsed.coverage,
9516
9530
  returned: selected.length,
9517
9531
  total: parsed.items.length,
9518
- truncated: parsed.coverage.truncated || selected.length < parsed.items.length
9532
+ truncated: parsed.coverage.truncated || selected.length < parsed.items.length || summaries.some((record) => record.evidenceTruncated)
9519
9533
  },
9520
- items: selected
9534
+ items: summaries
9521
9535
  }
9522
9536
  };
9523
9537
  }
@@ -11170,6 +11184,7 @@ function summarizeAttemptWaitingLogs(logs, actionId) {
11170
11184
 
11171
11185
  // src/domains/investigation/parser/projection/summarizeAttemptTrace.ts
11172
11186
  var evidenceLimit3 = 10;
11187
+ var consoleLimit = 5;
11173
11188
  var maxActionEvidenceBytes2 = 512;
11174
11189
  var maxSnapshotReconstructionBytes2 = 256 * 1024;
11175
11190
  function normalizedFailure(value) {
@@ -11185,7 +11200,7 @@ async function summarizeAttemptTrace(trace, attemptError) {
11185
11200
  const traceError = failure?.errorMessage ? normalizedFailure(failure.errorMessage) : undefined;
11186
11201
  const metadataError = attemptError ? normalizedFailure(attemptError) : undefined;
11187
11202
  const errorMatches = Boolean(traceError && metadataError && (metadataError.includes(traceError) || traceError.includes(metadataError)));
11188
- const toAction = (action) => {
11203
+ const toAction = (action, includeDetails) => {
11189
11204
  const stack = action.errorMessage === undefined ? [] : readTraceActionStack(trace, action).map((frame) => `${frame.file}:${frame.compiledLine}`);
11190
11205
  const error = action.errorMessage === undefined ? undefined : redactAndBoundAttemptEvidenceResult(action.errorMessage, maxActionEvidenceBytes2);
11191
11206
  const selector = action.selector === undefined ? undefined : redactAndBoundAttemptEvidenceResult(action.selector, maxActionEvidenceBytes2);
@@ -11203,9 +11218,11 @@ async function summarizeAttemptTrace(trace, attemptError) {
11203
11218
  ...action.startTime !== undefined && {
11204
11219
  startedAtMilliseconds: action.startTime
11205
11220
  },
11206
- stack: stack.slice(0, 20),
11207
- stackTruncated: stack.length > 20,
11208
- ...summarizeAttemptWaitingLogs(logs, action.id)
11221
+ ...includeDetails && {
11222
+ stack: stack.slice(0, 20),
11223
+ stackTruncated: stack.length > 20,
11224
+ ...summarizeAttemptWaitingLogs(logs, action.id)
11225
+ }
11209
11226
  };
11210
11227
  };
11211
11228
  const completed = chronologicallySortActions(actions.items.filter((action) => action.endTime !== undefined));
@@ -11215,10 +11232,10 @@ async function summarizeAttemptTrace(trace, attemptError) {
11215
11232
  limit: Number.MAX_SAFE_INTEGER,
11216
11233
  maxTextBytes: Number.MAX_SAFE_INTEGER
11217
11234
  });
11218
- const consoleItems = allConsoleEntries.items.slice(-evidenceLimit3);
11235
+ const consoleItems = allConsoleEntries.items.slice(-consoleLimit);
11219
11236
  const consoleSummaries = consoleItems.map((entry) => ({
11220
11237
  entry,
11221
- message: redactAndBoundAttemptEvidenceResult(entry.message, 1024)
11238
+ message: redactAndBoundAttemptEvidenceResult(entry.message, 256)
11222
11239
  }));
11223
11240
  const network = await listTraceNetwork(trace, {
11224
11241
  limit: Number.MAX_SAFE_INTEGER
@@ -11239,7 +11256,7 @@ async function summarizeAttemptTrace(trace, attemptError) {
11239
11256
  maxBytes: maxSnapshotReconstructionBytes2
11240
11257
  }) : undefined;
11241
11258
  const screenshot = pageSnapshot ? nearestScreenshotForSnapshot(trace, pageSnapshot.id) : undefined;
11242
- const projectedPage = page?.truncated ? { text: "", truncated: true } : page ? boundAttemptPageText(redactAttemptEvidence(projectToText(resolveSnapshot([page.html], 0), Number.MAX_SAFE_INTEGER))) : undefined;
11259
+ const projectedPage = page?.truncated ? { text: "", truncated: true } : page ? redactAndBoundAttemptEvidenceResult(projectToText(resolveSnapshot([page.html], 0), Number.MAX_SAFE_INTEGER), 2 * 1024) : undefined;
11243
11260
  return {
11244
11261
  actions: {
11245
11262
  coverage: {
@@ -11247,7 +11264,7 @@ async function summarizeAttemptTrace(trace, attemptError) {
11247
11264
  returned: selectedActions.length,
11248
11265
  truncated: actions.coverage.total > selectedActions.length
11249
11266
  },
11250
- items: selectedActions.map(toAction)
11267
+ items: selectedActions.map((action) => toAction(action, false))
11251
11268
  },
11252
11269
  browserConsole: {
11253
11270
  coverage: {
@@ -11258,14 +11275,17 @@ async function summarizeAttemptTrace(trace, attemptError) {
11258
11275
  items: consoleSummaries.map(({ entry, message }) => ({
11259
11276
  evidenceId: entry.id,
11260
11277
  message: message.text,
11278
+ ...message.truncated && { evidenceTruncated: true },
11261
11279
  type: entry.type
11262
11280
  }))
11263
11281
  },
11264
11282
  ...errorMatches && failure && {
11265
- failedBrowserAction: toAction(failure.action)
11283
+ failedBrowserAction: toAction(failure.action, true)
11266
11284
  },
11267
11285
  failedBrowserActionAttribution: errorMatches ? "trace-error-matches-attempt" : "none",
11268
- ...!errorMatches && lastCompleted && { lastCompletedBrowserAction: toAction(lastCompleted) },
11286
+ ...!errorMatches && lastCompleted && {
11287
+ lastCompletedBrowserAction: toAction(lastCompleted, true)
11288
+ },
11269
11289
  networkErrors,
11270
11290
  ...page && projectedPage && pageSnapshot && {
11271
11291
  pageState: {
@@ -11420,4 +11440,4 @@ export {
11420
11440
  investigate
11421
11441
  };
11422
11442
 
11423
- //# debugId=30384783C6AA2E7664756E2164756E21
11443
+ //# debugId=DDB8DC8EF65337B664756E2164756E21
@@ -11449,6 +11449,7 @@ var authErrorMessages = {
11449
11449
  rejected401: (noun) => `QA Wolf API rejected the${noun ? ` ${noun}` : ""} request (HTTP 401). Check your API key.`,
11450
11450
  rejected402: (noun) => `QA Wolf API refused the${noun ? ` ${noun}` : ""} request (HTTP 402): billing prevented it.`,
11451
11451
  rejected403: (noun) => `QA Wolf API rejected the${noun ? ` ${noun}` : ""} request (HTTP 403). Check that your API key has access to this environment.`,
11452
+ blocked403: (noun) => `The${noun ? ` ${noun}` : ""} request was blocked before it reached the QA Wolf API (HTTP 403), so your API key was not checked.`,
11452
11453
  notFound404Environment: (noun) => `QA Wolf API could not find ${noun ? `${noun} for that environment` : "that environment"} (HTTP 404). Check the --env value.`,
11453
11454
  notFound404Runner: (runnerId) => runnerId === undefined ? "That runner is not running (HTTP 404)." : `Runner ${runnerId} is not running (HTTP 404).`,
11454
11455
  runnerIsGone: "It was never launched, or it has since been terminated or idled out.",
@@ -11458,7 +11459,7 @@ var authErrorMessages = {
11458
11459
  notFound404Record: (noun, id) => `QA Wolf has no ${noun} ${id} (HTTP 404).`,
11459
11460
  notFound404: (noun) => noun === undefined ? "QA Wolf found nothing matching the request (HTTP 404)." : `QA Wolf found nothing matching the ${noun} request (HTTP 404).`,
11460
11461
  failedWithStatus: (status, noun) => `QA Wolf API${noun ? ` ${noun}` : ""} request failed (HTTP ${status}).`,
11461
- networkUnreachable: (baseUrl, noun) => `Could not reach the QA Wolf API at ${baseUrl}${noun ? ` to fetch ${noun}` : ""}. Check your network connection and QAWOLF_HOST_URL.`,
11462
+ 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.`,
11462
11463
  timedOut: (timeoutMs, noun) => `The QA Wolf API${noun ? ` ${noun}` : ""} request timed out after ${formatSeconds(timeoutMs)}. The work may still be finishing on the platform.`,
11463
11464
  unexpectedResponse: (noun) => `Unexpected${noun ? ` ${noun}` : ""} response from the QA Wolf API.`
11464
11465
  },
@@ -11842,10 +11843,10 @@ var lifecycleMessages = {
11842
11843
  launched: (id, url) => `Launched runner ${id}. ${pageAt(url)}`,
11843
11844
  launchedForCommand: (id, url) => `No runner was given, so launched ${id} for this command. Its browser is fresh: nothing has been run on it and nothing is signed in. It bills until it is terminated or idles out, so terminate it with qawolf runner terminate --runner ${id} when you are done. ${pageAt(url)}`,
11844
11845
  noRunnerIdForImport: `${noRunnerId} An install also needs a live run to go into, which a runner gets from qawolf runner run.`,
11845
- noRunnerIdForHighlight: `${noRunnerId} Highlighting also needs a live page to draw on, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
11846
- noRunnerIdForInspect: `${noRunnerId} Inspecting also needs a page, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
11846
+ noRunnerIdForHighlight: `${noRunnerId} A playwright runner has a page to draw on as soon as it launches.`,
11847
+ noRunnerIdForInspect: `${noRunnerId} A playwright runner can be inspected as soon as it launches, and any other runner once a flow has run on it with qawolf runner run.`,
11847
11848
  noRunnerIdForPromoteSnapshot: `${noRunnerId} A baseline is replaced on the runner that produced the screenshot, so it has to be the runner the diff came from.`,
11848
- noRunnerIdForScreenshot: `${noRunnerId} A screenshot also needs a screen, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
11849
+ noRunnerIdForScreenshot: `${noRunnerId} A playwright runner has a screen as soon as it launches, and any other runner once a flow has run on it with qawolf runner run.`,
11849
11850
  noRunnerId,
11850
11851
  wasNotRunning: (id) => `Runner ${id} was not running.`,
11851
11852
  terminated: (id) => `Terminated runner ${id}.`,
@@ -11900,6 +11901,7 @@ var runMessages = {
11900
11901
  unknownStream: (stream, known) => `"${stream}" is not a stream QA Wolf writes, so this read has nothing to return. QA Wolf writes ${known.join(", ")}.`,
11901
11902
  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.`,
11902
11903
  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.",
11904
+ 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.",
11903
11905
  targetMismatch: (runnerName, requiredRunnerName) => `This flow needs a ${requiredRunnerName} runner and ${runnerName} is running. Launch one with --name ${requiredRunnerName}.`
11904
11906
  };
11905
11907
 
@@ -13651,6 +13653,37 @@ function applyWorkspaceId(inputSchema, input, workspaceId) {
13651
13653
  return { ...input, workspaceId };
13652
13654
  }
13653
13655
 
13656
+ // src/core/fetchCause.ts
13657
+ var maxCauseDepth = 5;
13658
+ var maxCauseMessageLength = 120;
13659
+ var codePattern = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
13660
+ var urlPattern = /\bhttps?:\/\/\S+/g;
13661
+ function causeChain(options) {
13662
+ const { error, remainingDepth } = options;
13663
+ const { cause } = error;
13664
+ if (!(cause instanceof Error) || remainingDepth === 0)
13665
+ return [error];
13666
+ return [
13667
+ error,
13668
+ ...causeChain({ error: cause, remainingDepth: remainingDepth - 1 })
13669
+ ];
13670
+ }
13671
+ function shortMessage(message) {
13672
+ const withoutUrls = message.replace(urlPattern, "<url>").trim();
13673
+ return withoutUrls.length > maxCauseMessageLength ? `${withoutUrls.slice(0, maxCauseMessageLength)}…` : withoutUrls;
13674
+ }
13675
+ function describeFetchCause(error) {
13676
+ const chain = causeChain({ error, remainingDepth: maxCauseDepth });
13677
+ const root = chain.at(-1);
13678
+ const code = chain.map((link) => errorCode(link)).reverse().find((candidate) => candidate !== undefined && codePattern.test(candidate));
13679
+ const message = root === undefined ? "" : shortMessage(root.message);
13680
+ if (code === undefined)
13681
+ return message || undefined;
13682
+ if (!message || message.includes(code))
13683
+ return message || code;
13684
+ return `${code}: ${message}`;
13685
+ }
13686
+
13654
13687
  // src/shell/platform/describeNotFound.ts
13655
13688
  var m = authMessages.errors.request;
13656
13689
  var saysNothingMore = (reason) => /^(\w+ )*not ?found\.?$/i.test(reason.trim());
@@ -13768,13 +13801,19 @@ function describeRequestError(err, baseUrl, noun, notFound) {
13768
13801
  ...body
13769
13802
  };
13770
13803
  if (err.status === 403)
13771
- return { error: m2.request.rejected403(noun), ...body };
13804
+ return parseJson(err.body) === undefined ? { error: m2.request.blocked403(noun) } : { error: m2.request.rejected403(noun), ...body };
13772
13805
  if (err.status === 404)
13773
13806
  return describeNotFound(notFound, noun, reason);
13774
13807
  return { error: m2.request.failedWithStatus(err.status, noun), ...body };
13775
13808
  }
13776
13809
  if (err.kind === "network") {
13777
- return { error: m2.request.networkUnreachable(baseUrl, noun) };
13810
+ return {
13811
+ error: m2.request.networkUnreachable({
13812
+ baseUrl,
13813
+ cause: describeFetchCause(err.cause),
13814
+ noun
13815
+ })
13816
+ };
13778
13817
  }
13779
13818
  if (err.kind === "timeout") {
13780
13819
  return { error: m2.request.timedOut(err.timeoutMs, noun) };
@@ -15829,6 +15868,12 @@ function buildRunFileDelta(options) {
15829
15868
  return Object.keys(unchangedFiles).length === 0 ? { files: options.files, unchangedFiles: undefined } : { files, unchangedFiles };
15830
15869
  }
15831
15870
 
15871
+ // src/core/sentences.ts
15872
+ function appendSentence(text, sentence) {
15873
+ const punctuated = /[.!?]$/.test(text.trimEnd()) ? text.trimEnd() : `${text.trimEnd()}.`;
15874
+ return `${punctuated} ${sentence}`;
15875
+ }
15876
+
15832
15877
  // src/domains/interactiveRunner/runSubmitFailure.ts
15833
15878
  function describeRunSubmitFailure(failure) {
15834
15879
  const { failureReason } = failure;
@@ -15869,8 +15914,12 @@ async function sendRunFlowRequest(ctx, options, delta) {
15869
15914
  ...delta.unchangedFiles === undefined ? {} : { unchangedFiles: delta.unchangedFiles }
15870
15915
  }, runnerCallOptions);
15871
15916
  if (!result.ok) {
15917
+ const failure = runnerRequestFailure(result, options.resolved);
15872
15918
  return {
15873
- failure: runnerRequestFailure(result, options.resolved),
15919
+ failure: result.mayHaveArrived ? {
15920
+ ...failure,
15921
+ error: appendSentence(failure.error, interactiveRunnerMessages.submitLostMayHaveStarted)
15922
+ } : failure,
15874
15923
  type: "failed"
15875
15924
  };
15876
15925
  }
@@ -16074,4 +16123,4 @@ export {
16074
16123
  createRunnerSdk
16075
16124
  };
16076
16125
 
16077
- //# debugId=56D1BCF300A31BCC64756E2164756E21
16126
+ //# debugId=549062A3D36EB66B64756E2164756E21
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qawolf/cli",
3
- "version": "2.2.0",
3
+ "version": "2.2.2",
4
4
  "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
5
5
  "keywords": [
6
6
  "automation",
@@ -312,9 +312,9 @@ of calling `act` and then `screenshot`. One call performs the action and writes
312
312
  the screen the runner answers with: half the calls per step, and no delay to
313
313
  guess at between them.
314
314
 
315
- The full workflow is its own guide: how a runner is billed, why the first call
316
- must be a run, the order the commands go in, the see-and-act loop, `exec`, the
317
- recorder, reading history, staying alive, and an end-to-end example. **Run
315
+ The full workflow is its own guide: how a runner is billed, the order the
316
+ commands go in, the see-and-act loop, `exec`, the recorder, reading history,
317
+ staying alive, and an end-to-end example. **Run
318
318
  `qawolf help ref runner` before driving a runner for the first time.** It prints
319
319
  that guide and the help of every runner command, for the CLI version you have.
320
320
  Each command's `--help` carries its own part, so `qawolf runner exec --help`
@@ -11,28 +11,23 @@ Commands that target a runner find one in this order: `--runner`, then `QAWOLF_R
11
11
  - `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.
12
12
  - 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.
13
13
 
14
- If nothing names a runner, the commands that change something launch one and say so on stderr, naming it: `run`, `act` and `exec`. Read that announcement. The browser it just started is fresh: nothing has been run on it, nothing is signed in, and no page is open. Acting as though your earlier setup survived is the single most likely way to drive the wrong page.
14
+ If 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.
15
15
 
16
16
  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`.
17
17
 
18
18
  ## The order that matters
19
19
 
20
- A freshly launched runner has no screen. The virtual desktop starts with the runner's first run and nothing else starts it, so until you have run something:
20
+ A 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.
21
21
 
22
- - `screenshot` and `act` fail with exit code `2`, except `navigate`, which fails with exit code `1` (`action-failed`): it skips the screen but still needs the runner to have run something
23
- - `exec` fails with exit code `2`
24
- - `events recorder` reads as empty
25
-
26
- None of that is a fault, and none of it clears on its own. Only `qawolf runner run <flow>` starts the screen. A bare navigate does not: it fails until the first run, however long you wait.
27
-
28
- So the first thing you do to a new runner has to put a browser on it. That means a flow file and a `package.json` on disk, even if all you want is to drive the browser by hand; there is no "just give me a screen" call. Once one run has happened, the screenshot-and-act loop works for the rest of the runner's life. A `--lines` selection is the one call that does not need a run first.
22
+ Any 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.
29
23
 
30
24
  ## Exit codes
31
25
 
32
26
  Retry on the exit code, not on the message text:
33
27
 
34
- - `4` is transient, with one exception. The screen is up but cannot serve this instant: 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.
28
+ - `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.
35
29
  - `6` means the work ran out of the time it is given.
30
+ - `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.
36
31
  - `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.
37
32
  - `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.
38
33
 
@@ -40,14 +35,14 @@ Retry on the exit code, not on the message text:
40
35
 
41
36
  ## End to end
42
37
 
43
- Run from a directory holding a flow and a `package.json`. The run is what starts the screen, so it is not optional even though the goal here is to drive by hand.
38
+ Run from a directory holding a flow and a `package.json`.
44
39
 
45
40
  ```sh
46
41
  export QAWOLF_API_KEY=... # the only credential
47
42
  export QAWOLF_RUNNER_ID=agent-1 # so no command below needs --runner
48
43
 
49
44
  qawolf runner launch --id agent-1 --json # --id, not the variable; read .alreadyRunning and .url
50
- qawolf runner run flows/smoke.flow.ts --follow # starts the screen; exit 1 if it failed
45
+ qawolf runner run flows/smoke.flow.ts --follow # exit 1 if it failed
51
46
 
52
47
  qawolf runner act navigate --url https://example.com/login --screenshot step-1.jpg # then read step-1.jpg yourself
53
48
  qawolf runner act click --button left --x 480 --y 260 --screenshot step-2.jpg
@@ -115,7 +110,8 @@ Commands:
115
110
  to clear the highlight
116
111
  promote-snapshot [options] Accept a run's screenshot as the new baseline for an
117
112
  image diff, on the runner that produced it
118
- record Control video recording on a Playwright runner
113
+ record Control video recording on a browser, mobile, Windows, or
114
+ Mac runner
119
115
  list-recordings [options] Read a page of published video recordings, including
120
116
  after the runner terminates. Platform URLs persist; video
121
117
  URLs expire
@@ -144,8 +140,8 @@ Ids:
144
140
  fine id. Launching an id that is already running attaches to that runner
145
141
  instead of starting and billing a second one, and the answer says which
146
142
  happened: read `alreadyRunning`. Reusing one id is therefore the cheap and
147
- safe pattern. The same id with a different --name is refused rather than
148
- silently ignored.
143
+ safe pattern. --name does not change a runner that is already running: the
144
+ answer's `runnerName` says what you attached to.
149
145
 
150
146
  launch takes its id from --id and never reads QAWOLF_RUNNER_ID. A bare `qawolf
151
147
  runner launch` invents a random id, bills a pod under it and stores it, so a
@@ -164,9 +160,10 @@ The page:
164
160
  launched its own runner. It is a QA Wolf page showing what the runner is
165
161
  doing, where a person can also take over with their own mouse and keyboard.
166
162
  Hand it to a person who asks what your runner is up to. The page opens for
167
- anyone on the runner's team, however the runner was launched. There is nothing
168
- to see until the runner's first run starts its screen, so the page waits until
169
- then. You read the screen with `screenshot`, not with the page.
163
+ anyone on the runner's team, however the runner was launched. A playwright
164
+ runner's screen starts as it launches, showing a QA Wolf welcome page. Any
165
+ other runner's screen starts with its first run, so its page waits until then.
166
+ You read the screen with `screenshot`, not with the page.
170
167
 
171
168
  Browser or mobile:
172
169
  --name also chooses between a browser and a mobile device: --name android or
@@ -186,7 +183,7 @@ Usage: qawolf runner list [options]
186
183
  List the runners running on your team
187
184
 
188
185
  Options:
189
- --here Only the runners this directory launched
186
+ --here Only the runners this directory launched or QAWOLF_RUNNER_ID names
190
187
  -h, --help display help for command
191
188
 
192
189
  Examples:
@@ -195,12 +192,11 @@ Examples:
195
192
  $ qawolf runner list --json
196
193
 
197
194
  What the list holds:
198
- The list names the runners this directory has launched that are still running,
199
- and marks the one a command with no --runner would reach. It also includes the
200
- runner named by QAWOLF_RUNNER_ID even though this directory did not launch it,
201
- so a harness handed a runner sees it alongside the ones it started itself. Use
202
- the id column with --runner to address any of them; addressing one does not
203
- make it the default.
195
+ The list names every active runner on your team, marking the ones this
196
+ directory launched and the default, the one a command with no --runner would
197
+ reach. --here keeps only this directory's runners and the one QAWOLF_RUNNER_ID
198
+ names. Use the id column with --runner to address any of them; addressing one
199
+ does not make it the default.
204
200
 
205
201
  Every runner is looked up before it is listed, so a runner that idled out is
206
202
  absent rather than reported. The lookup neither starts a runner nor resets an
@@ -514,10 +510,11 @@ The recorder:
514
510
  `code` is absent on events with no call of their own, such as a navigation,
515
511
  which is why the first line falls back to `type`. Use these to turn a session
516
512
  you drove by pixel coordinates into durable selectors, and to check that a
517
- click landed on the element you meant rather than near it. The stream is empty
518
- until the runner's first run gives it a browser context, so an early empty
519
- answer means "not yet", not "broken". Do not add --json here: it wraps each
520
- line in an envelope and these field paths stop matching.
513
+ click landed on the element you meant rather than near it. The stream stays
514
+ empty while a playwright runner still shows its welcome page, and on any other
515
+ runner until its first run, so an early empty answer means "not yet", not
516
+ "broken". Do not add --json here: it wraps each line in an envelope and these
517
+ field paths stop matching.
521
518
 
522
519
  Following:
523
520
  --follow polls and prints as entries arrive. It is tail -f with a bound: it
@@ -566,9 +563,10 @@ Reading the screen:
566
563
  to stderr so nothing follows the image on stdout. A terminal on stdout is
567
564
  refused: redirect or pipe it.
568
565
 
569
- A runner has no screen until its first run, so until then screenshot exits 2.
570
- It never launches a runner. When you are about to act anyway, `act
571
- --screenshot` performs the action and returns the screen in one call.
566
+ A playwright runner's screen starts as it launches. Any other runner has no
567
+ screen until its first run, so until then screenshot exits 2 on it. It never
568
+ launches a runner. When you are about to act anyway, `act --screenshot`
569
+ performs the action and returns the screen in one call.
572
570
  ```
573
571
 
574
572
  ## qawolf runner act
@@ -594,8 +592,8 @@ Options:
594
592
  place of a separate screenshot. An action that did not take effect answers
595
593
  with one too. - writes it to stdout and moves the confirmation, JSON
596
594
  included, to stderr
597
- --scroll-x <delta> scroll: horizontal wheel delta
598
- --scroll-y <delta> scroll: vertical wheel delta
595
+ --scroll-x <delta> scroll: horizontal wheel delta, 0 when only --scroll-y is given
596
+ --scroll-y <delta> scroll: vertical wheel delta, 0 when only --scroll-x is given
599
597
  --selector <selector> tap or fill: the element to act on, as a screen object would find it. tap
600
598
  takes it in place of --x and --y
601
599
  --strategy <strategy> how --selector is resolved: xpath (default), ios-predicate or shadow
@@ -610,6 +608,7 @@ Examples:
610
608
  $ qawolf runner act click --button left --x 480 --y 260
611
609
  $ qawolf runner act type --text "hello@example.com"
612
610
  $ qawolf runner act keypress --keys Control a
611
+ $ qawolf runner act scroll --x 640 --y 400 --scroll-y 600
613
612
  $ qawolf runner act navigate --url https://example.com
614
613
  $ qawolf runner act drag --path '[{"x":10,"y":20},{"x":80,"y":90}]'
615
614
  $ qawolf runner act click --button left --x 480 --y 260 --screenshot step-4.jpg
@@ -670,10 +669,10 @@ Mobile:
670
669
  swipe and fill with action-not-supported-on-browser.
671
670
 
672
671
  Before the first run:
673
- A runner has no screen until its first run, so act exits 2 until then, except
674
- navigate, which exits 1 (action-failed): it skips the screen but still needs
675
- the runner to have run something. With no runner named at all, act launches
676
- one and says so on stderr.
672
+ A playwright runner's screen starts as it launches, so act works on it before
673
+ anything has run. Any other runner has no screen until its first run, so act
674
+ exits 2 on it until then. With no runner named at all, act launches one and
675
+ says so on stderr.
677
676
  ```
678
677
 
679
678
  ## qawolf runner actions
@@ -798,12 +797,12 @@ Scope:
798
797
  files, so the snippet can use your own page objects and helpers.
799
798
 
800
799
  Failures:
801
- exec exits 2 until the runner's first run, since there is no page to evaluate
802
- against. On a 4 the message says the snippet could not be evaluated, but a
803
- lost answer looks the same from outside, so treat a 4 from a snippet that
804
- changes something as "may have run" rather than "did not run", and check its
805
- effect before running it again. With no runner named at all, exec launches one
806
- and says so on stderr.
800
+ A playwright runner has a page to evaluate against as soon as it launches. On
801
+ a 4 the message says the snippet could not be evaluated, but a lost answer
802
+ looks the same from outside, so treat a 4 from a snippet that changes
803
+ something as "may have run" rather than "did not run", and check its effect
804
+ before running it again. With no runner named at all, exec launches one and
805
+ says so on stderr.
807
806
  ```
808
807
 
809
808
  ## qawolf runner inspect
@@ -1091,7 +1090,7 @@ Paths:
1091
1090
  ```text
1092
1091
  Usage: qawolf runner record [options] [command]
1093
1092
 
1094
- Control video recording on a Playwright runner
1093
+ Control video recording on a browser, mobile, Windows, or Mac runner
1095
1094
 
1096
1095
  Options:
1097
1096
  -h, --help display help for command