@qawolf/cli 2.2.0 → 2.2.1
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 +25 -39
- package/dist/runner-sdk.js +6 -5
- package/package.json +1 -1
- package/skills/qawolf-cli/SKILL.md +3 -3
- package/skills/qawolf-cli/references/runner.md +38 -41
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.",
|
|
@@ -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}
|
|
8939
|
-
noRunnerIdForInspect: `${noRunnerId}
|
|
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
|
|
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}.`,
|
|
@@ -15446,6 +15447,15 @@ function applyWorkspaceId(inputSchema, input, workspaceId) {
|
|
|
15446
15447
|
return { ...input, workspaceId };
|
|
15447
15448
|
}
|
|
15448
15449
|
|
|
15450
|
+
// src/core/parseJson.ts
|
|
15451
|
+
function parseJson(text) {
|
|
15452
|
+
try {
|
|
15453
|
+
return JSON.parse(text);
|
|
15454
|
+
} catch {
|
|
15455
|
+
return;
|
|
15456
|
+
}
|
|
15457
|
+
}
|
|
15458
|
+
|
|
15449
15459
|
// src/shell/platform/describeNotFound.ts
|
|
15450
15460
|
var m = authMessages.errors.request;
|
|
15451
15461
|
var saysNothingMore = (reason) => /^(\w+ )*not ?found\.?$/i.test(reason.trim());
|
|
@@ -15563,7 +15573,7 @@ function describeRequestError(err, baseUrl, noun, notFound) {
|
|
|
15563
15573
|
...body
|
|
15564
15574
|
};
|
|
15565
15575
|
if (err.status === 403)
|
|
15566
|
-
return { error: m2.request.rejected403(noun), ...body };
|
|
15576
|
+
return parseJson(err.body) === undefined ? { error: m2.request.blocked403(noun) } : { error: m2.request.rejected403(noun), ...body };
|
|
15567
15577
|
if (err.status === 404)
|
|
15568
15578
|
return describeNotFound(notFound, noun, reason);
|
|
15569
15579
|
return { error: m2.request.failedWithStatus(err.status, noun), ...body };
|
|
@@ -23624,7 +23634,7 @@ function startUpdateCheck(deps) {
|
|
|
23624
23634
|
// package.json
|
|
23625
23635
|
var package_default = {
|
|
23626
23636
|
name: "@qawolf/cli",
|
|
23627
|
-
version: "2.2.
|
|
23637
|
+
version: "2.2.1",
|
|
23628
23638
|
description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
|
|
23629
23639
|
keywords: [
|
|
23630
23640
|
"automation",
|
|
@@ -24206,15 +24216,6 @@ async function handleAgentGet(ctx, options, deps) {
|
|
|
24206
24216
|
// src/shell/agent/sessionStore.ts
|
|
24207
24217
|
import { join as join14 } from "node:path";
|
|
24208
24218
|
|
|
24209
|
-
// src/core/parseJson.ts
|
|
24210
|
-
function parseJson(text) {
|
|
24211
|
-
try {
|
|
24212
|
-
return JSON.parse(text);
|
|
24213
|
-
} catch {
|
|
24214
|
-
return;
|
|
24215
|
-
}
|
|
24216
|
-
}
|
|
24217
|
-
|
|
24218
24219
|
// src/shell/jsonFile.ts
|
|
24219
24220
|
var pendingWrites = 0;
|
|
24220
24221
|
async function readJsonFile(fs, path, schema) {
|
|
@@ -39397,7 +39398,7 @@ On mobile, send tap and swipe, never click or drag. The other browser actions, d
|
|
|
39397
39398
|
|
|
39398
39399
|
# Before the first run
|
|
39399
39400
|
|
|
39400
|
-
A runner
|
|
39401
|
+
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
39402
|
`;
|
|
39402
39403
|
|
|
39403
39404
|
// src/commands/runner/guides/actions.txt
|
|
@@ -39444,7 +39445,7 @@ History is not unbounded: a size cap drops the oldest entries on a long-lived ru
|
|
|
39444
39445
|
$ qawolf runner events recorder --tail 5 | jq -r '.code // .type'
|
|
39445
39446
|
$ qawolf runner events recorder --tail 5 | jq -r '[.locator] + (.alternates // []) | @tsv'
|
|
39446
39447
|
|
|
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
|
|
39448
|
+
\`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
39449
|
|
|
39449
39450
|
# Following
|
|
39450
39451
|
|
|
@@ -39471,7 +39472,7 @@ The snippet imports nothing of yours by default. Pass --file <path> to evaluate
|
|
|
39471
39472
|
|
|
39472
39473
|
# Failures
|
|
39473
39474
|
|
|
39474
|
-
|
|
39475
|
+
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
39476
|
`;
|
|
39476
39477
|
|
|
39477
39478
|
// src/commands/runner/guides/formatGuide.ts
|
|
@@ -39558,27 +39559,12 @@ It is a read with a cost: keeping the clock reset keeps a billed pod alive. Call
|
|
|
39558
39559
|
`;
|
|
39559
39560
|
|
|
39560
39561
|
// src/commands/runner/guides/launch.txt
|
|
39561
|
-
var launch_default =
|
|
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
|
-
`;
|
|
39562
|
+
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
39563
|
|
|
39578
39564
|
// src/commands/runner/guides/list.txt
|
|
39579
39565
|
var list_default = `# What the list holds
|
|
39580
39566
|
|
|
39581
|
-
The list names the
|
|
39567
|
+
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
39568
|
|
|
39583
39569
|
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
39570
|
|
|
@@ -39669,7 +39655,7 @@ var screenshot_default = `# Reading the screen
|
|
|
39669
39655
|
|
|
39670
39656
|
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
39657
|
|
|
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.
|
|
39658
|
+
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
39659
|
`;
|
|
39674
39660
|
|
|
39675
39661
|
// src/commands/runner/guides/stopOrTerminate.txt
|
|
@@ -39683,7 +39669,7 @@ Both succeed when there was nothing to do, and say which: \`wasRunning\` is fals
|
|
|
39683
39669
|
`;
|
|
39684
39670
|
|
|
39685
39671
|
// 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
|
|
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";
|
|
39687
39673
|
|
|
39688
39674
|
// src/commands/runner/guides/index.ts
|
|
39689
39675
|
var runnerGuides = {
|
|
@@ -40768,7 +40754,7 @@ async function handleRunnerList(ctx, options, deps) {
|
|
|
40768
40754
|
if (!listed.ok) {
|
|
40769
40755
|
return { ...failureFields(listed), exitCode: exitCodes.network };
|
|
40770
40756
|
}
|
|
40771
|
-
const items = options.here ? listed.items.filter((item) => item.launchedHere) : listed.items;
|
|
40757
|
+
const items = options.here ? listed.items.filter((item) => item.launchedHere || item.isDefault) : listed.items;
|
|
40772
40758
|
if (ctx.ui.mode === "json") {
|
|
40773
40759
|
ctx.ui.json(items);
|
|
40774
40760
|
return;
|
|
@@ -40844,7 +40830,7 @@ Examples:
|
|
|
40844
40830
|
$ qawolf runner keepalive --runner ci`;
|
|
40845
40831
|
function registerRunnerLifecycleCommands(runner, signals) {
|
|
40846
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));
|
|
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));
|
|
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));
|
|
40848
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));
|
|
40849
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));
|
|
40850
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));
|
|
@@ -41830,4 +41816,4 @@ createProgram({ signals }).parseAsync().catch(() => {
|
|
|
41830
41816
|
process.exitCode = 1;
|
|
41831
41817
|
}).finally(() => exitWhenIdle(typeof process.exitCode === "number" ? process.exitCode : 0));
|
|
41832
41818
|
|
|
41833
|
-
//# debugId=
|
|
41819
|
+
//# debugId=F8E2C24048CC67D764756E2164756E21
|
package/dist/runner-sdk.js
CHANGED
|
@@ -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.",
|
|
@@ -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}
|
|
11846
|
-
noRunnerIdForInspect: `${noRunnerId}
|
|
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
|
|
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}.`,
|
|
@@ -13768,7 +13769,7 @@ function describeRequestError(err, baseUrl, noun, notFound) {
|
|
|
13768
13769
|
...body
|
|
13769
13770
|
};
|
|
13770
13771
|
if (err.status === 403)
|
|
13771
|
-
return { error: m2.request.rejected403(noun), ...body };
|
|
13772
|
+
return parseJson(err.body) === undefined ? { error: m2.request.blocked403(noun) } : { error: m2.request.rejected403(noun), ...body };
|
|
13772
13773
|
if (err.status === 404)
|
|
13773
13774
|
return describeNotFound(notFound, noun, reason);
|
|
13774
13775
|
return { error: m2.request.failedWithStatus(err.status, noun), ...body };
|
|
@@ -16074,4 +16075,4 @@ export {
|
|
|
16074
16075
|
createRunnerSdk
|
|
16075
16076
|
};
|
|
16076
16077
|
|
|
16077
|
-
//# debugId=
|
|
16078
|
+
//# debugId=7D41A06F682D4C5564756E2164756E21
|
package/package.json
CHANGED
|
@@ -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,
|
|
316
|
-
|
|
317
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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`.
|
|
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 #
|
|
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
|
|
@@ -144,8 +139,8 @@ Ids:
|
|
|
144
139
|
fine id. Launching an id that is already running attaches to that runner
|
|
145
140
|
instead of starting and billing a second one, and the answer says which
|
|
146
141
|
happened: read `alreadyRunning`. Reusing one id is therefore the cheap and
|
|
147
|
-
safe pattern.
|
|
148
|
-
|
|
142
|
+
safe pattern. --name does not change a runner that is already running: the
|
|
143
|
+
answer's `runnerName` says what you attached to.
|
|
149
144
|
|
|
150
145
|
launch takes its id from --id and never reads QAWOLF_RUNNER_ID. A bare `qawolf
|
|
151
146
|
runner launch` invents a random id, bills a pod under it and stores it, so a
|
|
@@ -164,9 +159,10 @@ The page:
|
|
|
164
159
|
launched its own runner. It is a QA Wolf page showing what the runner is
|
|
165
160
|
doing, where a person can also take over with their own mouse and keyboard.
|
|
166
161
|
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.
|
|
168
|
-
|
|
169
|
-
|
|
162
|
+
anyone on the runner's team, however the runner was launched. A playwright
|
|
163
|
+
runner's screen starts as it launches, showing a QA Wolf welcome page. Any
|
|
164
|
+
other runner's screen starts with its first run, so its page waits until then.
|
|
165
|
+
You read the screen with `screenshot`, not with the page.
|
|
170
166
|
|
|
171
167
|
Browser or mobile:
|
|
172
168
|
--name also chooses between a browser and a mobile device: --name android or
|
|
@@ -186,7 +182,7 @@ Usage: qawolf runner list [options]
|
|
|
186
182
|
List the runners running on your team
|
|
187
183
|
|
|
188
184
|
Options:
|
|
189
|
-
--here Only the runners this directory launched
|
|
185
|
+
--here Only the runners this directory launched or QAWOLF_RUNNER_ID names
|
|
190
186
|
-h, --help display help for command
|
|
191
187
|
|
|
192
188
|
Examples:
|
|
@@ -195,12 +191,11 @@ Examples:
|
|
|
195
191
|
$ qawolf runner list --json
|
|
196
192
|
|
|
197
193
|
What the list holds:
|
|
198
|
-
The list names
|
|
199
|
-
and
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
make it the default.
|
|
194
|
+
The list names every active runner on your team, marking the ones this
|
|
195
|
+
directory launched and the default, the one a command with no --runner would
|
|
196
|
+
reach. --here keeps only this directory's runners and the one QAWOLF_RUNNER_ID
|
|
197
|
+
names. Use the id column with --runner to address any of them; addressing one
|
|
198
|
+
does not make it the default.
|
|
204
199
|
|
|
205
200
|
Every runner is looked up before it is listed, so a runner that idled out is
|
|
206
201
|
absent rather than reported. The lookup neither starts a runner nor resets an
|
|
@@ -514,10 +509,11 @@ The recorder:
|
|
|
514
509
|
`code` is absent on events with no call of their own, such as a navigation,
|
|
515
510
|
which is why the first line falls back to `type`. Use these to turn a session
|
|
516
511
|
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
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
line in an envelope and these
|
|
512
|
+
click landed on the element you meant rather than near it. The stream stays
|
|
513
|
+
empty while a playwright runner still shows its welcome page, and on any other
|
|
514
|
+
runner until its first run, so an early empty answer means "not yet", not
|
|
515
|
+
"broken". Do not add --json here: it wraps each line in an envelope and these
|
|
516
|
+
field paths stop matching.
|
|
521
517
|
|
|
522
518
|
Following:
|
|
523
519
|
--follow polls and prints as entries arrive. It is tail -f with a bound: it
|
|
@@ -566,9 +562,10 @@ Reading the screen:
|
|
|
566
562
|
to stderr so nothing follows the image on stdout. A terminal on stdout is
|
|
567
563
|
refused: redirect or pipe it.
|
|
568
564
|
|
|
569
|
-
A runner
|
|
570
|
-
|
|
571
|
-
|
|
565
|
+
A playwright runner's screen starts as it launches. Any other runner has no
|
|
566
|
+
screen until its first run, so until then screenshot exits 2 on it. It never
|
|
567
|
+
launches a runner. When you are about to act anyway, `act --screenshot`
|
|
568
|
+
performs the action and returns the screen in one call.
|
|
572
569
|
```
|
|
573
570
|
|
|
574
571
|
## qawolf runner act
|
|
@@ -670,10 +667,10 @@ Mobile:
|
|
|
670
667
|
swipe and fill with action-not-supported-on-browser.
|
|
671
668
|
|
|
672
669
|
Before the first run:
|
|
673
|
-
A runner
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
670
|
+
A playwright runner's screen starts as it launches, so act works on it before
|
|
671
|
+
anything has run. Any other runner has no screen until its first run, so act
|
|
672
|
+
exits 2 on it until then. With no runner named at all, act launches one and
|
|
673
|
+
says so on stderr.
|
|
677
674
|
```
|
|
678
675
|
|
|
679
676
|
## qawolf runner actions
|
|
@@ -798,12 +795,12 @@ Scope:
|
|
|
798
795
|
files, so the snippet can use your own page objects and helpers.
|
|
799
796
|
|
|
800
797
|
Failures:
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
798
|
+
A playwright runner has a page to evaluate against as soon as it launches. On
|
|
799
|
+
a 4 the message says the snippet could not be evaluated, but a lost answer
|
|
800
|
+
looks the same from outside, so treat a 4 from a snippet that changes
|
|
801
|
+
something as "may have run" rather than "did not run", and check its effect
|
|
802
|
+
before running it again. With no runner named at all, exec launches one and
|
|
803
|
+
says so on stderr.
|
|
807
804
|
```
|
|
808
805
|
|
|
809
806
|
## qawolf runner inspect
|