@qawolf/cli 2.4.0 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.js CHANGED
@@ -8969,7 +8969,6 @@ var runMessages = {
8969
8969
  envFileUnparseable: (reason) => `The --env-file could not be read. ${reason}`,
8970
8970
  envFileUnreadable: (path) => `No env file at ${path}. Pass a path that exists, or drop --env-file to send no environment.`,
8971
8971
  envIdBlank: "--env-id was given nothing. Pass the id or alias of a QA Wolf environment, or drop the flag to send no environment.",
8972
- envIdWithEnvFile: "--env-id and --env-file both give the run its environment, so only one may be passed. Use --env-id for a QA Wolf environment, which QA Wolf reads itself, or --env-file for a dotenv file on this machine.",
8973
8972
  fileNotCollected: (path) => `"${path}" is not one of the files that travel to a runner. It must be inside the current directory and end in .ts, .tsx, .js, .mjs, .cjs or .json.`,
8974
8973
  fileUnreadable: (path, reason) => `${path} is one of the files that travel to a runner, but it could not be read: ${reason}. Move it out of the current directory, or make it readable.`,
8975
8974
  filesUnreadable: (reason) => `One of the files that travel to a runner could not be read: ${reason}.`,
@@ -8996,7 +8995,9 @@ var runMessages = {
8996
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.`,
8997
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.",
8998
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.",
8999
- targetMismatch: (runnerName, requiredRunnerName) => `This flow needs a ${requiredRunnerName} runner and ${runnerName} is running. Launch one with --name ${requiredRunnerName}.`
8998
+ targetMismatch: (runnerName, requiredRunnerName) => `This flow needs a ${requiredRunnerName} runner and ${runnerName} is running. Launch one with --name ${requiredRunnerName}.`,
8999
+ varMalformed: (assignment) => `--env-var takes NAME=VALUE, and "${assignment}" names no variable.`,
9000
+ varRepeated: (name) => `--env-var gives ${name} more than once, so the run's value is unclear. Pass it once.`
9000
9001
  };
9001
9002
 
9002
9003
  // src/core/messages/interactiveRunner/index.ts
@@ -24023,7 +24024,7 @@ function startUpdateCheck(deps) {
24023
24024
  // package.json
24024
24025
  var package_default = {
24025
24026
  name: "@qawolf/cli",
24026
- version: "2.4.0",
24027
+ version: "2.5.0",
24027
24028
  description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
24028
24029
  keywords: [
24029
24030
  "automation",
@@ -40047,13 +40048,18 @@ A --lines selection is the one call that does not need a run first. If the runne
40047
40048
 
40048
40049
  # Environment variables
40049
40050
 
40050
- A run takes one of two. --env-id names a QA Wolf environment by id or alias, the same reference \`qawolf flows\` takes as --env. --env-file .env gives the run the variables in a dotenv file, in the format \`qawolf flows pull\` writes. Passing both is refused: each gives the run its whole environment, so there is no order in which they would combine.
40051
+ A run's variables come from up to three places, each on top of the one before:
40052
+ - --env-id names a QA Wolf environment by id or alias, the same reference \`qawolf flows\` takes as --env.
40053
+ - --env-file .env reads a dotenv file, in the format \`qawolf flows pull\` writes.
40054
+ - --env-var NAME=VALUE, or --var for short, gives one variable, and can be repeated. It splits on the first =, so a value may hold one.
40051
40055
 
40052
- A run with neither flag falls back to QAWOLF_ENVIRONMENT, the same variable \`qawolf flows\` reads, so one export covers both. The run says on stderr which environment it picked up, because those variables reach your flow's code and a run should never be given an environment silently. --env-id wins over it, and --env-file suppresses it, so a run reading a dotenv file is not handed a second environment on top.
40056
+ A later source replaces a variable of the same name from an earlier one, for this run only; the QA Wolf environment itself is not changed. Use that to run against something the environment does not hold, such as a new app build: \`--env-var RUN_INPUT_PATH=uploads/app.apk\`.
40057
+
40058
+ A run with no --env-id falls back to QAWOLF_ENVIRONMENT, the same variable \`qawolf flows\` reads, so one export covers both. The run says on stderr which environment it picked up, because those variables reach your flow's code and a run should never be given an environment silently. --env-id wins over it, and --env-file alone suppresses it, so a run reading a dotenv file is not handed a second environment unless you name one with --env-id. --env-var keeps it, since an --env-var adds to the environment rather than replacing it.
40053
40059
 
40054
40060
  Prefer --env-id. QA Wolf reads and decrypts the environment itself, so the values never leave the server, nothing has to be pulled to disk first, and no size limit applies to them. It is the only way to run a flow whose environment holds something large, such as a session cookie.
40055
40061
 
40056
- A run that sends its own variables with --env-file may carry at most 200 of them, each value at most 16 KiB. Names follow what a shell accepts, and QAWOLF_TEAM_ID is reserved because QA Wolf sets it from the key you authenticated with. All of that is refused before a runner is addressed, naming the variable at fault.
40062
+ The variables sent with --env-file and --env-var together may number at most 200, each value at most 16 KiB. Names follow what a shell accepts, and QAWOLF_TEAM_ID is reserved because QA Wolf sets it from the key you authenticated with. QAWOLF_ENVIRONMENT_ID, QAWOLF_ENVIRONMENT_NAME and QAWOLF_TEAM_API_KEY are set by QA Wolf for a run given an environment, and replace any value of yours. All of the refusals are made before a runner is addressed, naming the variable at fault.
40057
40063
  `;
40058
40064
 
40059
40065
  // src/commands/runner/guides/screenshot.txt
@@ -41651,12 +41657,36 @@ function buildRunEnvironment(content) {
41651
41657
  ok: false
41652
41658
  };
41653
41659
  }
41654
- const checked = runEnvironmentSchema.safeParse(parsed);
41660
+ return checkRunEnvironment(parsed);
41661
+ }
41662
+ function checkRunEnvironment(environment) {
41663
+ const checked = runEnvironmentSchema.safeParse(environment);
41655
41664
  if (!checked.success) {
41656
41665
  return { error: prettifyError(checked.error), ok: false };
41657
41666
  }
41658
41667
  return { environment: checked.data, ok: true };
41659
41668
  }
41669
+ function parseRunVariables(assignments) {
41670
+ const environment = {};
41671
+ for (const assignment of assignments) {
41672
+ const separator = assignment.indexOf("=");
41673
+ const name = separator === -1 ? "" : assignment.slice(0, separator).trim();
41674
+ if (name === "") {
41675
+ return {
41676
+ error: interactiveRunnerMessages.varMalformed(assignment),
41677
+ ok: false
41678
+ };
41679
+ }
41680
+ if (Object.hasOwn(environment, name)) {
41681
+ return {
41682
+ error: interactiveRunnerMessages.varRepeated(name),
41683
+ ok: false
41684
+ };
41685
+ }
41686
+ environment[name] = assignment.slice(separator + 1);
41687
+ }
41688
+ return { environment, ok: true };
41689
+ }
41660
41690
 
41661
41691
  // src/domains/interactiveRunner/collectFiles.ts
41662
41692
  async function collectRunFiles2(deps, roots) {
@@ -41685,12 +41715,12 @@ var refused = (error, exitCode) => ({
41685
41715
  });
41686
41716
  async function prepareRun(options, deps) {
41687
41717
  const explicitEnvId = options.envId?.trim();
41688
- if (explicitEnvId !== undefined && options.envFile !== undefined) {
41689
- return refused(interactiveRunnerMessages.envIdWithEnvFile, exitCodes.invalidArgs);
41690
- }
41691
41718
  if (explicitEnvId === "") {
41692
41719
  return refused(interactiveRunnerMessages.envIdBlank, exitCodes.invalidArgs);
41693
41720
  }
41721
+ const fromVars = parseRunVariables(options.vars);
41722
+ if (!fromVars.ok)
41723
+ return refused(fromVars.error, exitCodes.invalidArgs);
41694
41724
  const fromEnvVar = deps.env["QAWOLF_ENVIRONMENT"]?.trim();
41695
41725
  const environmentId = explicitEnvId ?? (options.envFile === undefined && fromEnvVar ? fromEnvVar : undefined);
41696
41726
  const linesFilePath = options.linesFile === undefined ? undefined : toCollectedPath(deps.cwd, options.linesFile);
@@ -41703,11 +41733,18 @@ async function prepareRun(options, deps) {
41703
41733
  if (check.type !== "ok") {
41704
41734
  return refused(describeRunFilesCheck(check), exitCodes.invalidArgs);
41705
41735
  }
41706
- const environment = await readEnvironment(options.envFile, deps);
41707
- if (environment !== undefined && !environment.ok) {
41708
- return refused(environment.error, exitCodes.config);
41736
+ const fromFile = await readEnvironment(options.envFile, deps);
41737
+ if (fromFile !== undefined && !fromFile.ok) {
41738
+ return refused(fromFile.error, exitCodes.config);
41709
41739
  }
41710
- const given = environment?.ok === true ? environment.environment : undefined;
41740
+ const combined = fromFile === undefined && options.vars.length === 0 ? undefined : checkRunEnvironment({
41741
+ ...fromFile?.environment,
41742
+ ...fromVars.environment
41743
+ });
41744
+ if (combined !== undefined && !combined.ok) {
41745
+ return refused(combined.error, exitCodes.invalidArgs);
41746
+ }
41747
+ const given = combined?.environment;
41711
41748
  if (options.lines === undefined) {
41712
41749
  return options.linesFile === undefined ? {
41713
41750
  environment: given,
@@ -41902,7 +41939,8 @@ async function handleRunnerRun(ctx, options, deps) {
41902
41939
  envFile: options.envFile,
41903
41940
  envId: options.envId,
41904
41941
  lines: options.lines,
41905
- linesFile: options.linesFile
41942
+ linesFile: options.linesFile,
41943
+ vars: options.vars
41906
41944
  }, deps);
41907
41945
  if (!prepared.ok) {
41908
41946
  return { error: prepared.error, exitCode: prepared.exitCode };
@@ -41965,9 +42003,10 @@ Examples:
41965
42003
  $ qawolf runner run flows/checkout.flow.ts --follow --logs
41966
42004
  $ qawolf runner run flows/checkout.flow.ts --lines 12-40
41967
42005
  $ qawolf runner run flows/checkout.flow.ts --lines 4-9 --lines-file pages/login.ts
41968
- $ qawolf runner run flows/checkout.flow.ts --env-id staging`;
42006
+ $ qawolf runner run flows/checkout.flow.ts --env-id staging
42007
+ $ qawolf runner run flows/checkout.flow.ts --env-var RUN_INPUT_PATH=uploads/app.apk`;
41969
42008
  function registerRunCommand(runner, signals) {
41970
- declareCommandKind(runner.command("run <flowFile>"), "write").description("Run a flow on an interactive runner, shipping the flow and what it imports").option("--follow", "Report the run's status until it settles: in progress, then passed or failed", false).option("--logs", "Stream every log line the run produces while following. Implies --follow", false).option("--run-events", "Stream the run's progress events as JSON lines while following. Implies --follow", false).option("--recorder-events", "Stream the browser actions the runner records as JSON lines while following, from an anchor taken just before submission: the recorder is runner-wide, not run-scoped. Implies --follow", false).option("--env-id <env>", "QA Wolf environment whose variables the run is given, by id or alias. Defaults to QAWOLF_ENVIRONMENT. QA Wolf reads and decrypts them itself, so they never leave the server and no size limit applies to them").option("--env-file <path>", "Dotenv file on this machine whose variables the run is given. Pass this or --env-id, not both").option("--lines <start-end>", "Run only these 1-indexed lines against the browser as it stands, instead of the whole flow from a fresh one").option("--lines-file <path>", "File the --lines range lives in. Defaults to <flowFile>; pass it only when the lines are in another file, such as a page object").option("--runner <id>", runnerFlagDescription).option("--timeout <seconds>", "Give up following after this long. Following keeps the runner alive, so a run that never settles would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", runExamples2).addHelpText("after", runnerGuides.run).action((flowFile, opts, command) => withRunnerContext(signals, (ctx) => handleRunnerRun(ctx, {
42009
+ declareCommandKind(runner.command("run <flowFile>"), "write").description("Run a flow on an interactive runner, shipping the flow and what it imports").option("--follow", "Report the run's status until it settles: in progress, then passed or failed", false).option("--logs", "Stream every log line the run produces while following. Implies --follow", false).option("--run-events", "Stream the run's progress events as JSON lines while following. Implies --follow", false).option("--recorder-events", "Stream the browser actions the runner records as JSON lines while following, from an anchor taken just before submission: the recorder is runner-wide, not run-scoped. Implies --follow", false).option("--env-id <env>", "QA Wolf environment whose variables the run is given, by id or alias. Defaults to QAWOLF_ENVIRONMENT unless --env-file is passed. QA Wolf reads and decrypts them itself, so they never leave the server and no size limit applies to them").option("--env-file <path>", "Dotenv file on this machine whose variables the run is given. With --env-id, they go on top of that environment's").option("--var, --env-var <name=value>", "One variable for this run only, on top of the environment and --env-file; repeat for several", collectValue, []).option("--lines <start-end>", "Run only these 1-indexed lines against the browser as it stands, instead of the whole flow from a fresh one").option("--lines-file <path>", "File the --lines range lives in. Defaults to <flowFile>; pass it only when the lines are in another file, such as a page object").option("--runner <id>", runnerFlagDescription).option("--timeout <seconds>", "Give up following after this long. Following keeps the runner alive, so a run that never settles would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", runExamples2).addHelpText("after", runnerGuides.run).action((flowFile, opts, command) => withRunnerContext(signals, (ctx) => handleRunnerRun(ctx, {
41971
42010
  entryPoint: flowFile,
41972
42011
  envFile: opts.envFile,
41973
42012
  envId: opts.envId,
@@ -41978,7 +42017,8 @@ function registerRunCommand(runner, signals) {
41978
42017
  recorderEvents: opts.recorderEvents,
41979
42018
  runEvents: opts.runEvents,
41980
42019
  runner: opts.runner,
41981
- timeout: opts.timeout
42020
+ timeout: opts.timeout,
42021
+ vars: opts.envVar
41982
42022
  }, runnerDeps(ctx)))(opts, command));
41983
42023
  }
41984
42024
 
@@ -42230,4 +42270,4 @@ createProgram({ signals }).parseAsync().catch(() => {
42230
42270
  process.exitCode = 1;
42231
42271
  }).finally(() => exitWhenIdle(typeof process.exitCode === "number" ? process.exitCode : 0));
42232
42272
 
42233
- //# debugId=F41EBBF938D33FDB64756E2164756E21
42273
+ //# debugId=38256B41DD722AA164756E2164756E21
@@ -12208,7 +12208,6 @@ var runMessages = {
12208
12208
  envFileUnparseable: (reason) => `The --env-file could not be read. ${reason}`,
12209
12209
  envFileUnreadable: (path) => `No env file at ${path}. Pass a path that exists, or drop --env-file to send no environment.`,
12210
12210
  envIdBlank: "--env-id was given nothing. Pass the id or alias of a QA Wolf environment, or drop the flag to send no environment.",
12211
- envIdWithEnvFile: "--env-id and --env-file both give the run its environment, so only one may be passed. Use --env-id for a QA Wolf environment, which QA Wolf reads itself, or --env-file for a dotenv file on this machine.",
12212
12211
  fileNotCollected: (path) => `"${path}" is not one of the files that travel to a runner. It must be inside the current directory and end in .ts, .tsx, .js, .mjs, .cjs or .json.`,
12213
12212
  fileUnreadable: (path, reason) => `${path} is one of the files that travel to a runner, but it could not be read: ${reason}. Move it out of the current directory, or make it readable.`,
12214
12213
  filesUnreadable: (reason) => `One of the files that travel to a runner could not be read: ${reason}.`,
@@ -12235,7 +12234,9 @@ var runMessages = {
12235
12234
  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.`,
12236
12235
  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.",
12237
12236
  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.",
12238
- targetMismatch: (runnerName, requiredRunnerName) => `This flow needs a ${requiredRunnerName} runner and ${runnerName} is running. Launch one with --name ${requiredRunnerName}.`
12237
+ targetMismatch: (runnerName, requiredRunnerName) => `This flow needs a ${requiredRunnerName} runner and ${runnerName} is running. Launch one with --name ${requiredRunnerName}.`,
12238
+ varMalformed: (assignment) => `--env-var takes NAME=VALUE, and "${assignment}" names no variable.`,
12239
+ varRepeated: (name) => `--env-var gives ${name} more than once, so the run's value is unclear. Pass it once.`
12239
12240
  };
12240
12241
 
12241
12242
  // src/core/messages/interactiveRunner/index.ts
@@ -16096,12 +16097,36 @@ function buildRunEnvironment(content) {
16096
16097
  ok: false
16097
16098
  };
16098
16099
  }
16099
- const checked = runEnvironmentSchema.safeParse(parsed);
16100
+ return checkRunEnvironment(parsed);
16101
+ }
16102
+ function checkRunEnvironment(environment) {
16103
+ const checked = runEnvironmentSchema.safeParse(environment);
16100
16104
  if (!checked.success) {
16101
16105
  return { error: prettifyError(checked.error), ok: false };
16102
16106
  }
16103
16107
  return { environment: checked.data, ok: true };
16104
16108
  }
16109
+ function parseRunVariables(assignments) {
16110
+ const environment = {};
16111
+ for (const assignment of assignments) {
16112
+ const separator = assignment.indexOf("=");
16113
+ const name = separator === -1 ? "" : assignment.slice(0, separator).trim();
16114
+ if (name === "") {
16115
+ return {
16116
+ error: interactiveRunnerMessages.varMalformed(assignment),
16117
+ ok: false
16118
+ };
16119
+ }
16120
+ if (Object.hasOwn(environment, name)) {
16121
+ return {
16122
+ error: interactiveRunnerMessages.varRepeated(name),
16123
+ ok: false
16124
+ };
16125
+ }
16126
+ environment[name] = assignment.slice(separator + 1);
16127
+ }
16128
+ return { environment, ok: true };
16129
+ }
16105
16130
 
16106
16131
  // src/domains/interactiveRunner/collectFiles.ts
16107
16132
  async function collectRunFiles2(deps, roots) {
@@ -16130,12 +16155,12 @@ var refused = (error, exitCode) => ({
16130
16155
  });
16131
16156
  async function prepareRun(options, deps) {
16132
16157
  const explicitEnvId = options.envId?.trim();
16133
- if (explicitEnvId !== undefined && options.envFile !== undefined) {
16134
- return refused(interactiveRunnerMessages.envIdWithEnvFile, exitCodes.invalidArgs);
16135
- }
16136
16158
  if (explicitEnvId === "") {
16137
16159
  return refused(interactiveRunnerMessages.envIdBlank, exitCodes.invalidArgs);
16138
16160
  }
16161
+ const fromVars = parseRunVariables(options.vars);
16162
+ if (!fromVars.ok)
16163
+ return refused(fromVars.error, exitCodes.invalidArgs);
16139
16164
  const fromEnvVar = deps.env["QAWOLF_ENVIRONMENT"]?.trim();
16140
16165
  const environmentId = explicitEnvId ?? (options.envFile === undefined && fromEnvVar ? fromEnvVar : undefined);
16141
16166
  const linesFilePath = options.linesFile === undefined ? undefined : toCollectedPath(deps.cwd, options.linesFile);
@@ -16148,11 +16173,18 @@ async function prepareRun(options, deps) {
16148
16173
  if (check.type !== "ok") {
16149
16174
  return refused(describeRunFilesCheck(check), exitCodes.invalidArgs);
16150
16175
  }
16151
- const environment = await readEnvironment(options.envFile, deps);
16152
- if (environment !== undefined && !environment.ok) {
16153
- return refused(environment.error, exitCodes.config);
16176
+ const fromFile = await readEnvironment(options.envFile, deps);
16177
+ if (fromFile !== undefined && !fromFile.ok) {
16178
+ return refused(fromFile.error, exitCodes.config);
16179
+ }
16180
+ const combined = fromFile === undefined && options.vars.length === 0 ? undefined : checkRunEnvironment({
16181
+ ...fromFile?.environment,
16182
+ ...fromVars.environment
16183
+ });
16184
+ if (combined !== undefined && !combined.ok) {
16185
+ return refused(combined.error, exitCodes.invalidArgs);
16154
16186
  }
16155
- const given = environment?.ok === true ? environment.environment : undefined;
16187
+ const given = combined?.environment;
16156
16188
  if (options.lines === undefined) {
16157
16189
  return options.linesFile === undefined ? {
16158
16190
  environment: given,
@@ -16379,7 +16411,8 @@ function createRunVerbs({ deps, platformClient }) {
16379
16411
  envFile: undefined,
16380
16412
  envId: environment === "ambient" ? undefined : environment.id,
16381
16413
  lines: toLineRange(selection),
16382
- linesFile: toLinesFile(selection)
16414
+ linesFile: toLinesFile(selection),
16415
+ vars: []
16383
16416
  }, deps);
16384
16417
  if (!prepared.ok)
16385
16418
  return { error: prepared.error, ok: false };
@@ -16474,4 +16507,4 @@ export {
16474
16507
  createRunnerSdk
16475
16508
  };
16476
16509
 
16477
- //# debugId=87F77F3A03400AEC64756E2164756E21
16510
+ //# debugId=F5D9BC086D8A595464756E2164756E21
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qawolf/cli",
3
- "version": "2.4.0",
3
+ "version": "2.5.0",
4
4
  "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
5
5
  "keywords": [
6
6
  "automation",
@@ -40,7 +40,9 @@ exported variables, so pass the selected environment explicitly instead of
40
40
  rediscovering it. Check the command's help for its environment flag: variable
41
41
  commands use `--environment-id`; `qawolf flows run` uses `--env`; and
42
42
  `qawolf runner run` uses `--env-id`, which falls back to `QAWOLF_ENVIRONMENT`
43
- when neither it nor `--env-file` is passed.
43
+ when neither it nor `--env-file` is passed. To give one run a value the
44
+ environment does not hold, keep the environment and add
45
+ `--env-var NAME=VALUE`; it replaces the environment's value for that run only.
44
46
 
45
47
  If multiple environments are returned and the task context does not identify
46
48
  the target, ask instead of guessing. Do not default to the newest environment.
@@ -358,38 +358,42 @@ Usage: qawolf runner run [options] <flowFile>
358
358
  Run a flow on an interactive runner, shipping the flow and what it imports
359
359
 
360
360
  Options:
361
- --follow Report the run's status until it settles: in progress, then passed or failed
362
- (default: false)
363
- --logs Stream every log line the run produces while following. Implies --follow
364
- (default: false)
365
- --run-events Stream the run's progress events as JSON lines while following. Implies
366
- --follow (default: false)
367
- --recorder-events Stream the browser actions the runner records as JSON lines while following,
368
- from an anchor taken just before submission: the recorder is runner-wide, not
369
- run-scoped. Implies --follow (default: false)
370
- --env-id <env> QA Wolf environment whose variables the run is given, by id or alias.
371
- Defaults to QAWOLF_ENVIRONMENT. QA Wolf reads and decrypts them itself, so
372
- they never leave the server and no size limit applies to them
373
- --env-file <path> Dotenv file on this machine whose variables the run is given. Pass this or
374
- --env-id, not both
375
- --lines <start-end> Run only these 1-indexed lines against the browser as it stands, instead of
376
- the whole flow from a fresh one
377
- --lines-file <path> File the --lines range lives in. Defaults to <flowFile>; pass it only when
378
- the lines are in another file, such as a page object
379
- --runner <id> Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored
380
- runner
381
- --timeout <seconds> Give up following after this long. Following keeps the runner alive, so a run
382
- that never settles would otherwise bill until the terminal closed (default:
383
- "3600")
384
- -h, --help display help for command
361
+ --follow Report the run's status until it settles: in progress, then passed
362
+ or failed (default: false)
363
+ --logs Stream every log line the run produces while following. Implies
364
+ --follow (default: false)
365
+ --run-events Stream the run's progress events as JSON lines while following.
366
+ Implies --follow (default: false)
367
+ --recorder-events Stream the browser actions the runner records as JSON lines while
368
+ following, from an anchor taken just before submission: the
369
+ recorder is runner-wide, not run-scoped. Implies --follow (default:
370
+ false)
371
+ --env-id <env> QA Wolf environment whose variables the run is given, by id or
372
+ alias. Defaults to QAWOLF_ENVIRONMENT unless --env-file is passed.
373
+ QA Wolf reads and decrypts them itself, so they never leave the
374
+ server and no size limit applies to them
375
+ --env-file <path> Dotenv file on this machine whose variables the run is given. With
376
+ --env-id, they go on top of that environment's
377
+ --var, --env-var <name=value> One variable for this run only, on top of the environment and
378
+ --env-file; repeat for several (default: [])
379
+ --lines <start-end> Run only these 1-indexed lines against the browser as it stands,
380
+ instead of the whole flow from a fresh one
381
+ --lines-file <path> File the --lines range lives in. Defaults to <flowFile>; pass it
382
+ only when the lines are in another file, such as a page object
383
+ --runner <id> Runner to target. Defaults to QAWOLF_RUNNER_ID, then this
384
+ directory's stored runner
385
+ --timeout <seconds> Give up following after this long. Following keeps the runner
386
+ alive, so a run that never settles would otherwise bill until the
387
+ terminal closed (default: "3600")
388
+ -h, --help display help for command
385
389
 
386
390
  Global Options:
387
- --workspace-id <id> Workspace to work in for this command only. Defaults to the one 'qawolf auth
388
- switch' saved, and is never saved itself
389
- -V, --version output the version number
390
- --verbose Enable debug logging to stderr
391
- --json Output as JSON
392
- --agent Output for agent consumption
391
+ --workspace-id <id> Workspace to work in for this command only. Defaults to the one
392
+ 'qawolf auth switch' saved, and is never saved itself
393
+ -V, --version output the version number
394
+ --verbose Enable debug logging to stderr
395
+ --json Output as JSON
396
+ --agent Output for agent consumption
393
397
 
394
398
  Examples:
395
399
  $ qawolf runner run flows/checkout.flow.ts
@@ -398,6 +402,7 @@ Examples:
398
402
  $ qawolf runner run flows/checkout.flow.ts --lines 12-40
399
403
  $ qawolf runner run flows/checkout.flow.ts --lines 4-9 --lines-file pages/login.ts
400
404
  $ qawolf runner run flows/checkout.flow.ts --env-id staging
405
+ $ qawolf runner run flows/checkout.flow.ts --env-var RUN_INPUT_PATH=uploads/app.apk
401
406
 
402
407
  What travels:
403
408
  run ships the flow file, everything it imports, and your package.json and
@@ -487,29 +492,39 @@ Running part of a flow:
487
492
  see.
488
493
 
489
494
  Environment variables:
490
- A run takes one of two. --env-id names a QA Wolf environment by id or alias,
491
- the same reference `qawolf flows` takes as --env. --env-file .env gives the
492
- run the variables in a dotenv file, in the format `qawolf flows pull` writes.
493
- Passing both is refused: each gives the run its whole environment, so there is
494
- no order in which they would combine.
495
-
496
- A run with neither flag falls back to QAWOLF_ENVIRONMENT, the same variable
495
+ A run's variables come from up to three places, each on top of the one before:
496
+ - --env-id names a QA Wolf environment by id or alias, the same reference
497
+ `qawolf flows` takes as --env.
498
+ - --env-file .env reads a dotenv file, in the format `qawolf flows pull`
499
+ writes.
500
+ - --env-var NAME=VALUE, or --var for short, gives one variable, and can be
501
+ repeated. It splits on the first =, so a value may hold one.
502
+
503
+ A later source replaces a variable of the same name from an earlier one, for
504
+ this run only; the QA Wolf environment itself is not changed. Use that to run
505
+ against something the environment does not hold, such as a new app build:
506
+ `--env-var RUN_INPUT_PATH=uploads/app.apk`.
507
+
508
+ A run with no --env-id falls back to QAWOLF_ENVIRONMENT, the same variable
497
509
  `qawolf flows` reads, so one export covers both. The run says on stderr which
498
510
  environment it picked up, because those variables reach your flow's code and a
499
511
  run should never be given an environment silently. --env-id wins over it, and
500
- --env-file suppresses it, so a run reading a dotenv file is not handed a
501
- second environment on top.
512
+ --env-file alone suppresses it, so a run reading a dotenv file is not handed a
513
+ second environment unless you name one with --env-id. --env-var keeps it,
514
+ since an --env-var adds to the environment rather than replacing it.
502
515
 
503
516
  Prefer --env-id. QA Wolf reads and decrypts the environment itself, so the
504
517
  values never leave the server, nothing has to be pulled to disk first, and no
505
518
  size limit applies to them. It is the only way to run a flow whose environment
506
519
  holds something large, such as a session cookie.
507
520
 
508
- A run that sends its own variables with --env-file may carry at most 200 of
509
- them, each value at most 16 KiB. Names follow what a shell accepts, and
521
+ The variables sent with --env-file and --env-var together may number at most
522
+ 200, each value at most 16 KiB. Names follow what a shell accepts, and
510
523
  QAWOLF_TEAM_ID is reserved because QA Wolf sets it from the key you
511
- authenticated with. All of that is refused before a runner is addressed,
512
- naming the variable at fault.
524
+ authenticated with. QAWOLF_ENVIRONMENT_ID, QAWOLF_ENVIRONMENT_NAME and
525
+ QAWOLF_TEAM_API_KEY are set by QA Wolf for a run given an environment, and
526
+ replace any value of yours. All of the refusals are made before a runner is
527
+ addressed, naming the variable at fault.
513
528
  ```
514
529
 
515
530
  ## qawolf runner events