@qawolf/cli 2.4.0 → 2.6.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
@@ -17132,6 +17133,16 @@ var defaultIdSchemas = {
17132
17133
  };
17133
17134
  var workspaceForEnvironmentRef = (workspace) => workspace.optional().describe("The workspace the environment belongs to, which an alias resolves in. Read it from whoami.");
17134
17135
 
17136
+ // node_modules/@qawolf/api-contracts/dist/v1/issue/files.js
17137
+ var maxAttachedFilesPerRequest = 10;
17138
+ var attachedFilePathsSchema = array(teamStoragePathSchema).min(1).max(maxAttachedFilesPerRequest).refine((filePaths) => new Set(filePaths).size === filePaths.length, "filePaths must be unique");
17139
+ var attachedFilePathsDescription = "Paths of files in the team's storage to attach to the bug report, such as the files the bug was reproduced with. " + `At most ${maxAttachedFilesPerRequest} files, each at most 100 MB. ` + "QA Wolf keeps a copy of each file as it is now, so later changes to the original do not change the report. " + "If any path has no file, nothing is attached and the error names the path.";
17140
+ var issueFileSchema = object({
17141
+ fileId: string2().describe("The id of the attached file."),
17142
+ name: string2().describe("The file's name, taken from the last segment of the path it was attached from."),
17143
+ sizeBytes: number2().int().nonnegative()
17144
+ });
17145
+
17135
17146
  // node_modules/@qawolf/api-contracts/dist/v1/build/resource.js
17136
17147
  var buildPlatformSchema = _enum(["android", "ios"]).describe("The platform the build runs on, read from its file type.");
17137
17148
  var buildIdSchema = string2().regex(/^[a-z0-9]{24}obld$/, "Expected a build id from build.requestUpload.").describe("The id of the build, from build.requestUpload.");
@@ -18741,6 +18752,36 @@ var makeListBuildsContract = (ids) => {
18741
18752
  };
18742
18753
  };
18743
18754
 
18755
+ // node_modules/@qawolf/api-contracts/dist/v1/build/requestDownload.js
18756
+ var makeRequestBuildDownloadContract = (ids) => {
18757
+ const input = object({
18758
+ buildId: buildIdSchema,
18759
+ workspaceId: ids.workspace.optional().describe("The workspace of the build. Required when authenticating with an organization or user API key.")
18760
+ });
18761
+ const output = object({
18762
+ expiresAt: exports_iso.datetime().describe("When readUrl stops working. Request another one after it."),
18763
+ fileName: string2().describe("The name of the build's file."),
18764
+ readUrl: string2().describe('Fetch the build\'s file from here, for example `curl -o app.apk "<readUrl>"`.')
18765
+ });
18766
+ return {
18767
+ annotationJustifications: {
18768
+ destructiveHint: "Does not change the build or its file.",
18769
+ openWorldHint: "Access is limited to the build files of the authorized workspace.",
18770
+ readOnlyHint: "Returns an expiring read URL for a build's file."
18771
+ },
18772
+ annotations: {
18773
+ destructiveHint: false,
18774
+ openWorldHint: false,
18775
+ readOnlyHint: true
18776
+ },
18777
+ description: "Get a URL to download a build's file. Deleted builds can be downloaded while their file exists. Answers 404 when the file has expired.",
18778
+ input,
18779
+ kind: "read",
18780
+ name: "build.requestDownload",
18781
+ output
18782
+ };
18783
+ };
18784
+
18744
18785
  // node_modules/@qawolf/api-contracts/dist/v1/build/requestUpload.js
18745
18786
  var maxBuildFileBytes = 500 * 1024 * 1024;
18746
18787
  var makeRequestBuildUploadContract = (ids) => {
@@ -18781,6 +18822,7 @@ var makeBuildContracts = (ids) => ({
18781
18822
  delete: makeDeleteBuildContract(ids),
18782
18823
  get: makeGetBuildContract(ids),
18783
18824
  list: makeListBuildsContract(ids),
18825
+ requestDownload: makeRequestBuildDownloadContract(ids),
18784
18826
  requestUpload: makeRequestBuildUploadContract(ids)
18785
18827
  });
18786
18828
 
@@ -19388,6 +19430,7 @@ var makeGetEnvironmentVariableContract = (ids) => {
19388
19430
  });
19389
19431
  const output = object({
19390
19432
  missingNames: array(string2()).describe("Requested names the environment does not have, sorted alphabetically."),
19433
+ secretNames: array(string2()).describe("Requested names that hold write-only secrets, sorted alphabetically. Their values are never returned; flows still receive them at run time."),
19391
19434
  variables: array(object({
19392
19435
  name: string2().describe("The stored variable name."),
19393
19436
  value: string2().describe("The variable's secret value. Handle as a secret.")
@@ -19404,7 +19447,7 @@ var makeGetEnvironmentVariableContract = (ids) => {
19404
19447
  openWorldHint: false,
19405
19448
  readOnlyHint: true
19406
19449
  },
19407
- description: "Read the values of named environment variables in one call. Values are secrets. Names that do not exist go to missingNames and do not fail the call.",
19450
+ description: "Read the values of named environment variables in one call. Values are secrets. Names that do not exist go to missingNames and write-only secrets go to secretNames; neither fails the call.",
19408
19451
  input,
19409
19452
  kind: "read",
19410
19453
  name: "environment.getVariable",
@@ -19844,6 +19887,7 @@ var makeIssueResourceSchema = (ids) => resource({
19844
19887
  coveredFlowIds: array(ids.flow).describe("The flows a coverage request covers. Always empty on bug reports and blockers, whose flows are listed under reproductions."),
19845
19888
  createdAt: exports_coerce.date().describe("When the issue was created."),
19846
19889
  description: string2().describe("The issue description in Markdown."),
19890
+ files: array(issueFileSchema).default([]).describe("Files attached to a bug report, oldest first. Always empty on blockers and coverage requests."),
19847
19891
  issueId: ids.issue,
19848
19892
  name: string2(),
19849
19893
  number: number2().int(),
@@ -20101,6 +20145,34 @@ var makeAddFlowsToIssueContract = (ids) => {
20101
20145
  };
20102
20146
  };
20103
20147
 
20148
+ // node_modules/@qawolf/api-contracts/dist/v1/issue/attachFiles.js
20149
+ var makeAttachFilesToIssueContract = (ids) => {
20150
+ const input = object({
20151
+ filePaths: attachedFilePathsSchema.describe(attachedFilePathsDescription),
20152
+ issueId: ids.issue
20153
+ });
20154
+ const output = object({
20155
+ issue: makeIssueResourceSchema(ids)
20156
+ });
20157
+ return {
20158
+ annotationJustifications: {
20159
+ destructiveHint: "Adds files to the bug report without removing or replacing the ones already attached.",
20160
+ openWorldHint: "Copies files within QA Wolf storage without publishing anything outside QA Wolf.",
20161
+ readOnlyHint: "Copies files from the team's storage and attaches the copies to a bug report."
20162
+ },
20163
+ annotations: {
20164
+ destructiveHint: false,
20165
+ openWorldHint: false,
20166
+ readOnlyHint: false
20167
+ },
20168
+ description: "Attach files from the team's storage to a bug report owned by the caller's team, for example the files a bug was reproduced with. " + "Files already attached stay attached. Upload a file with file.requestUpload first.",
20169
+ input,
20170
+ kind: "write",
20171
+ name: "issue.attachFiles",
20172
+ output
20173
+ };
20174
+ };
20175
+
20104
20176
  // node_modules/@qawolf/api-contracts/dist/v1/issue/create.js
20105
20177
  var makeCreateIssueContract = (ids) => {
20106
20178
  const commonFields = {
@@ -20112,6 +20184,7 @@ var makeCreateIssueContract = (ids) => {
20112
20184
  const input = discriminatedUnion("type", [
20113
20185
  object({
20114
20186
  ...commonFields,
20187
+ filePaths: attachedFilePathsSchema.optional().describe(attachedFilePathsDescription),
20115
20188
  type: literal("bug")
20116
20189
  }),
20117
20190
  object({
@@ -20307,6 +20380,19 @@ var makeUpdateIssueContract = (ids) => {
20307
20380
  };
20308
20381
  };
20309
20382
 
20383
+ // node_modules/@qawolf/api-contracts/dist/v1/issue/contracts.js
20384
+ var makeIssueContracts = (ids) => ({
20385
+ addFlows: makeAddFlowsToIssueContract(ids),
20386
+ attachFiles: makeAttachFilesToIssueContract(ids),
20387
+ create: makeCreateIssueContract(ids),
20388
+ decideSuggestion: makeDecideSuggestionContract(ids),
20389
+ find: makeFindIssuesContract(ids),
20390
+ get: makeGetIssueContract(ids),
20391
+ listActivity: makeListIssueActivityContract(ids),
20392
+ removeFlows: makeRemoveFlowsFromIssueContract(ids),
20393
+ update: makeUpdateIssueContract(ids)
20394
+ });
20395
+
20310
20396
  // node_modules/@qawolf/api-contracts/dist/v1/legacyTrigger/resource.js
20311
20397
  var namedIdentity = object({ id: string2(), name: string2() });
20312
20398
  var branchScope = union([
@@ -20660,6 +20746,39 @@ var makeFlowFailureSchema = (ids) => {
20660
20746
  });
20661
20747
  };
20662
20748
 
20749
+ // node_modules/@qawolf/api-contracts/dist/v1/run/versions.js
20750
+ var extensibleValue = (values, meanings) => string2().describe(`One of ${values.join(", ")}; newer servers may add values, so ignore any you don't know. ${meanings}`);
20751
+ var attemptCount = number2().int().positive().describe("How many attempts reported it.");
20752
+ var runBuildVersionSchema = object({
20753
+ appId: string2().describe("The package name (Android) or bundle ID (iOS) of the app."),
20754
+ expected: object({
20755
+ buildId: buildIdSchema,
20756
+ version: string2().optional()
20757
+ }).optional().describe("The run's build of this app. Absent for an app it got none of."),
20758
+ kind: extensibleValue(["build", "info"], "build: the run got a build of this app. info: any other app an attempt installed, such as a companion app. It has no warnings."),
20759
+ observed: array(object({
20760
+ attempts: attemptCount,
20761
+ buildId: buildIdSchema.optional().describe("Absent when the file is not one of the team's builds."),
20762
+ version: string2().optional()
20763
+ })).describe("What attempts installed, one entry per build or version."),
20764
+ platform: buildPlatformSchema,
20765
+ unreportedAttempts: number2().int().nonnegative().describe("Finished attempts that reported no installed app, such as web attempts or attempts on an older Flows SDK."),
20766
+ warnings: array(extensibleValue(["changedDuringRun", "notTested", "unknownApp"], "changedDuringRun: attempts installed different builds of the run's app. notTested: attempts reported installs on this platform, but none installed the run's build. unknownApp: an attempt installed a file of this app that is not the run's build.")).describe("Why the installed apps may not be what the run should test.")
20767
+ });
20768
+ var runSiteVersionSchema = object({
20769
+ expected: object({
20770
+ from: extensibleValue(["deployment", "latestDeployment"], "deployment: the run's own deployment. latestDeployment: the environment's latest successful deployment before the run."),
20771
+ version: string2().describe("The deployed commit.")
20772
+ }).optional().describe("The commit the run should see. Only on the origin the deployment reported as its target. Absent when no deployment names a commit and a target, or the deployment has a service."),
20773
+ observed: array(object({
20774
+ attempts: attemptCount,
20775
+ source: extensibleValue(["header", "meta", "versionPath", "frameworkBuildId", "fingerprint"], "Where the attempt read the version."),
20776
+ version: string2()
20777
+ })).describe("What attempts saw, one entry per version and source."),
20778
+ origin: string2().describe("The site origin the attempts visited."),
20779
+ warnings: array(extensibleValue(["changedDuringRun", "unexpectedVersion"], "changedDuringRun: attempts saw different versions from one source. unexpectedVersion: the site served another commit than expected.")).describe("Why the site may not be the version the run should test.")
20780
+ });
20781
+
20663
20782
  // node_modules/@qawolf/api-contracts/dist/v1/run/get.js
20664
20783
  var makeGetRunContract = (ids) => {
20665
20784
  const flowStatus = _enum(publicRunStatusValues);
@@ -20686,8 +20805,10 @@ var makeGetRunContract = (ids) => {
20686
20805
  ...makeRunSummaryFields(ids),
20687
20806
  blockingBugCount: number2().int().nonnegative().describe("How many bugs this run found are blocking: still open, and priority urgent, high, or unprioritized — unprioritized counts because nobody has ruled it out yet. This is what `failed` is derived from, so it explains a failure rather than adding a second verdict: gate on `status`, then read this to say how many bugs are holding the build. It counts a bug filed against a later run by an investigation that carried over from this one, and it drops a bug once that bug is resolved."),
20688
20807
  builds: array(makeBuildResourceSchema(ids)).describe("The builds the run installs, one per app and platform. Empty when the run has none."),
20808
+ buildVersions: array(runBuildVersionSchema).describe("The apps the run's attempts installed, one per app and platform, with warnings. Empty when no attempt reported an install and the run has no builds."),
20689
20809
  flows,
20690
- runId: ids.run.describe("The run this response describes. Treat it as canonical: it can differ from the id you asked for. A deploy notification returns a run id before the run exists, and if a second notification for the same commit is folded into an earlier run, that id resolves to the earlier run instead.")
20810
+ runId: ids.run.describe("The run this response describes. Treat it as canonical: it can differ from the id you asked for. A deploy notification returns a run id before the run exists, and if a second notification for the same commit is folded into an earlier run, that id resolves to the earlier run instead."),
20811
+ siteVersions: array(runSiteVersionSchema).describe("The versions the run's attempts saw on each site origin, with warnings. Empty when no attempt reported one.")
20691
20812
  }, { urlFieldDescription: "Absolute URL of the run page." });
20692
20813
  return {
20693
20814
  annotationJustifications: {
@@ -21037,7 +21158,7 @@ var makeLaunchRunnerContract = (ids) => {
21037
21158
  openWorldHint: true,
21038
21159
  readOnlyHint: false
21039
21160
  },
21040
- description: "Launch an interactive runner on the caller's team under an id the caller chooses. Send `initialUrl` so its browser comes up on the page the work starts from, which saves a separate navigation and the browser's cold start. Launching the same id again returns the runner already running rather than starting a second one, and the same id with a different runnerName is refused. A runner is not permanent: it terminates on its own after a period of inactivity, and launching the same id after that starts and bills a new runner, so read `alreadyRunning` to tell which happened. A success means the runner is answering: the call waits for the pod it started to come up, so the very next call to the runner reaches it. If the pod does not come up in time the call fails instead, leaving the runner running, and launching the same id again attaches to it.",
21161
+ description: "Launch an interactive runner on the caller's team under an id the caller chooses. Send `initialUrl` so its browser comes up on the page the work starts from, which saves a separate navigation and the browser's cold start. Launching the same id again returns the runner already running rather than starting a second one, whatever runnerName is sent, so read `runnerName` in the answer for what is running. A runner is not permanent: it terminates on its own after a period of inactivity, and launching the same id after that starts and bills a new runner, so read `alreadyRunning` to tell which happened. A success means the runner is answering: the call waits for the pod it started to come up, so the very next call to the runner reaches it. If the pod does not come up in time the call fails instead, leaving the runner running, and launching the same id again attaches to it.",
21041
21162
  input,
21042
21163
  kind: "write",
21043
21164
  name: "runner.launch",
@@ -21185,17 +21306,14 @@ var unchangedFilesSchema = record(string2(), string2().min(1)).superRefine((hash
21185
21306
  var makeRunFlowOnRunnerContract = (ids) => {
21186
21307
  const input = object({
21187
21308
  entryPointPath: runFilePathSchema.describe("Path of the flow file to run, as it appears in `files`."),
21188
- env: runEnvironmentSchema.optional().describe("Environment variables to make available to the run."),
21189
- environmentId: ids.environmentRef.optional().describe("A QA Wolf environment whose variables the run is given, by id or alias. QA Wolf reads and decrypts them itself, so they never travel in the request and the count and length limits on `env` do not apply to them. The run also gets `QAWOLF_ENVIRONMENT_ID`, `QAWOLF_ENVIRONMENT_NAME` and `QAWOLF_TEAM_API_KEY`, as a cloud run on that environment does, so a flow can save environment variables with `@qawolf/testkit`. Send this or `env`, not both."),
21309
+ env: runEnvironmentSchema.optional().describe("Environment variables to make available to the run. With `environmentId`, they are added on top of that environment's variables for this run only, replacing any of the same name; the environment itself is not changed."),
21310
+ environmentId: ids.environmentRef.optional().describe("A QA Wolf environment whose variables the run is given, by id or alias. QA Wolf reads and decrypts them itself, so they never travel in the request and the count and length limits on `env` do not apply to them. The run also gets `QAWOLF_ENVIRONMENT_ID`, `QAWOLF_ENVIRONMENT_NAME` and `QAWOLF_TEAM_API_KEY`, as a cloud run on that environment does, so a flow can save environment variables with `@qawolf/testkit`; `env` cannot replace these three."),
21190
21311
  files: runFilesSchema.describe("Every file the run needs keyed by its path — the flow file, everything it imports, package.json and tsconfig.json. A runner holds no copy of your project, so what runs is exactly what is sent here."),
21191
21312
  flowId: ids.flow.optional().describe("The QA Wolf flow this run is for. The run then sees it as `QAWOLF_WORKFLOW_ID`, the same value a platform run of that flow sees, so fixtures named and cleaned up by it match across both. Omitted, the flow whose file is at `entryPointPath` on the named environment's flow-code branch stands in; a file not in QA Wolf yet, or a run given no environment, leaves the run with no `QAWOLF_WORKFLOW_ID`."),
21192
21313
  id: runnerIdSchema.describe("Id of the runner to run the flow on."),
21193
21314
  selection: runSelectionSchema.optional().describe("Run only these lines, inside the page the runner is already on, instead of running the whole flow from a fresh browser. Omit to run the whole entry point."),
21194
21315
  unchangedFiles: unchangedFilesSchema.optional().describe("Files this runner already holds from an earlier run, keyed by path with a hex SHA-256 of the content it should hold. Send this to make `files` only what changed. The runner refuses with `needs-full-sync` if it holds none of a referenced path, so it never runs something other than what was asked for. Omit it to send every file."),
21195
21316
  workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
21196
- }).refine((request) => request.env === undefined || request.environmentId === undefined, {
21197
- error: "Send env or environmentId, not both. An environment's variables are taken as they are stored, so there is no order in which the two would combine.",
21198
- path: ["environmentId"]
21199
21317
  }).refine((request) => Object.hasOwn(request.files, request.entryPointPath), {
21200
21318
  error: "The entry point must be one of the files.",
21201
21319
  path: ["files"]
@@ -21482,16 +21600,7 @@ var makeContractsV1 = (ids) => {
21482
21600
  update: makeUpdateFlowContract(resolvedIds)
21483
21601
  },
21484
21602
  investigation: makeInvestigationContracts(resolvedIds),
21485
- issue: {
21486
- addFlows: makeAddFlowsToIssueContract(resolvedIds),
21487
- create: makeCreateIssueContract(resolvedIds),
21488
- decideSuggestion: makeDecideSuggestionContract(resolvedIds),
21489
- find: makeFindIssuesContract(resolvedIds),
21490
- get: makeGetIssueContract(resolvedIds),
21491
- listActivity: makeListIssueActivityContract(resolvedIds),
21492
- removeFlows: makeRemoveFlowsFromIssueContract(resolvedIds),
21493
- update: makeUpdateIssueContract(resolvedIds)
21494
- },
21603
+ issue: makeIssueContracts(resolvedIds),
21495
21604
  legacyTrigger: makeLegacyTriggerContracts(resolvedIds),
21496
21605
  mcpServer: {
21497
21606
  connect: makeConnectMcpServerContract(resolvedIds)
@@ -24023,7 +24132,7 @@ function startUpdateCheck(deps) {
24023
24132
  // package.json
24024
24133
  var package_default = {
24025
24134
  name: "@qawolf/cli",
24026
- version: "2.4.0",
24135
+ version: "2.6.0",
24027
24136
  description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
24028
24137
  keywords: [
24029
24138
  "automation",
@@ -24095,7 +24204,7 @@ var package_default = {
24095
24204
  "@clack/prompts": "1.5.1",
24096
24205
  "@napi-rs/keyring": "1.3.0",
24097
24206
  "@oxc-node/core": "0.1.0",
24098
- "@qawolf/api-contracts": "0.104.0",
24207
+ "@qawolf/api-contracts": "0.107.0",
24099
24208
  "@qawolf/emails": "1.1.1",
24100
24209
  "@qawolf/flow-targets": "2.0.0",
24101
24210
  "@qawolf/flows": "0.3.0",
@@ -40047,13 +40156,18 @@ A --lines selection is the one call that does not need a run first. If the runne
40047
40156
 
40048
40157
  # Environment variables
40049
40158
 
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.
40159
+ A run's variables come from up to three places, each on top of the one before:
40160
+ - --env-id names a QA Wolf environment by id or alias, the same reference \`qawolf flows\` takes as --env.
40161
+ - --env-file .env reads a dotenv file, in the format \`qawolf flows pull\` writes.
40162
+ - --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.
40163
+
40164
+ 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\`.
40051
40165
 
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.
40166
+ 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
40167
 
40054
40168
  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
40169
 
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.
40170
+ 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
40171
  `;
40058
40172
 
40059
40173
  // src/commands/runner/guides/screenshot.txt
@@ -41651,12 +41765,36 @@ function buildRunEnvironment(content) {
41651
41765
  ok: false
41652
41766
  };
41653
41767
  }
41654
- const checked = runEnvironmentSchema.safeParse(parsed);
41768
+ return checkRunEnvironment(parsed);
41769
+ }
41770
+ function checkRunEnvironment(environment) {
41771
+ const checked = runEnvironmentSchema.safeParse(environment);
41655
41772
  if (!checked.success) {
41656
41773
  return { error: prettifyError(checked.error), ok: false };
41657
41774
  }
41658
41775
  return { environment: checked.data, ok: true };
41659
41776
  }
41777
+ function parseRunVariables(assignments) {
41778
+ const environment = {};
41779
+ for (const assignment of assignments) {
41780
+ const separator = assignment.indexOf("=");
41781
+ const name = separator === -1 ? "" : assignment.slice(0, separator).trim();
41782
+ if (name === "") {
41783
+ return {
41784
+ error: interactiveRunnerMessages.varMalformed(assignment),
41785
+ ok: false
41786
+ };
41787
+ }
41788
+ if (Object.hasOwn(environment, name)) {
41789
+ return {
41790
+ error: interactiveRunnerMessages.varRepeated(name),
41791
+ ok: false
41792
+ };
41793
+ }
41794
+ environment[name] = assignment.slice(separator + 1);
41795
+ }
41796
+ return { environment, ok: true };
41797
+ }
41660
41798
 
41661
41799
  // src/domains/interactiveRunner/collectFiles.ts
41662
41800
  async function collectRunFiles2(deps, roots) {
@@ -41685,12 +41823,12 @@ var refused = (error, exitCode) => ({
41685
41823
  });
41686
41824
  async function prepareRun(options, deps) {
41687
41825
  const explicitEnvId = options.envId?.trim();
41688
- if (explicitEnvId !== undefined && options.envFile !== undefined) {
41689
- return refused(interactiveRunnerMessages.envIdWithEnvFile, exitCodes.invalidArgs);
41690
- }
41691
41826
  if (explicitEnvId === "") {
41692
41827
  return refused(interactiveRunnerMessages.envIdBlank, exitCodes.invalidArgs);
41693
41828
  }
41829
+ const fromVars = parseRunVariables(options.vars);
41830
+ if (!fromVars.ok)
41831
+ return refused(fromVars.error, exitCodes.invalidArgs);
41694
41832
  const fromEnvVar = deps.env["QAWOLF_ENVIRONMENT"]?.trim();
41695
41833
  const environmentId = explicitEnvId ?? (options.envFile === undefined && fromEnvVar ? fromEnvVar : undefined);
41696
41834
  const linesFilePath = options.linesFile === undefined ? undefined : toCollectedPath(deps.cwd, options.linesFile);
@@ -41703,11 +41841,18 @@ async function prepareRun(options, deps) {
41703
41841
  if (check.type !== "ok") {
41704
41842
  return refused(describeRunFilesCheck(check), exitCodes.invalidArgs);
41705
41843
  }
41706
- const environment = await readEnvironment(options.envFile, deps);
41707
- if (environment !== undefined && !environment.ok) {
41708
- return refused(environment.error, exitCodes.config);
41844
+ const fromFile = await readEnvironment(options.envFile, deps);
41845
+ if (fromFile !== undefined && !fromFile.ok) {
41846
+ return refused(fromFile.error, exitCodes.config);
41709
41847
  }
41710
- const given = environment?.ok === true ? environment.environment : undefined;
41848
+ const combined = fromFile === undefined && options.vars.length === 0 ? undefined : checkRunEnvironment({
41849
+ ...fromFile?.environment,
41850
+ ...fromVars.environment
41851
+ });
41852
+ if (combined !== undefined && !combined.ok) {
41853
+ return refused(combined.error, exitCodes.invalidArgs);
41854
+ }
41855
+ const given = combined?.environment;
41711
41856
  if (options.lines === undefined) {
41712
41857
  return options.linesFile === undefined ? {
41713
41858
  environment: given,
@@ -41902,7 +42047,8 @@ async function handleRunnerRun(ctx, options, deps) {
41902
42047
  envFile: options.envFile,
41903
42048
  envId: options.envId,
41904
42049
  lines: options.lines,
41905
- linesFile: options.linesFile
42050
+ linesFile: options.linesFile,
42051
+ vars: options.vars
41906
42052
  }, deps);
41907
42053
  if (!prepared.ok) {
41908
42054
  return { error: prepared.error, exitCode: prepared.exitCode };
@@ -41965,9 +42111,10 @@ Examples:
41965
42111
  $ qawolf runner run flows/checkout.flow.ts --follow --logs
41966
42112
  $ qawolf runner run flows/checkout.flow.ts --lines 12-40
41967
42113
  $ 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`;
42114
+ $ qawolf runner run flows/checkout.flow.ts --env-id staging
42115
+ $ qawolf runner run flows/checkout.flow.ts --env-var RUN_INPUT_PATH=uploads/app.apk`;
41969
42116
  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, {
42117
+ 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
42118
  entryPoint: flowFile,
41972
42119
  envFile: opts.envFile,
41973
42120
  envId: opts.envId,
@@ -41978,7 +42125,8 @@ function registerRunCommand(runner, signals) {
41978
42125
  recorderEvents: opts.recorderEvents,
41979
42126
  runEvents: opts.runEvents,
41980
42127
  runner: opts.runner,
41981
- timeout: opts.timeout
42128
+ timeout: opts.timeout,
42129
+ vars: opts.envVar
41982
42130
  }, runnerDeps(ctx)))(opts, command));
41983
42131
  }
41984
42132
 
@@ -42230,4 +42378,4 @@ createProgram({ signals }).parseAsync().catch(() => {
42230
42378
  process.exitCode = 1;
42231
42379
  }).finally(() => exitWhenIdle(typeof process.exitCode === "number" ? process.exitCode : 0));
42232
42380
 
42233
- //# debugId=F41EBBF938D33FDB64756E2164756E21
42381
+ //# debugId=5F33B8D66BC6D61964756E2164756E21
@@ -7365,6 +7365,16 @@ var defaultIdSchemas = {
7365
7365
  };
7366
7366
  var workspaceForEnvironmentRef = (workspace) => workspace.optional().describe("The workspace the environment belongs to, which an alias resolves in. Read it from whoami.");
7367
7367
 
7368
+ // node_modules/@qawolf/api-contracts/dist/v1/issue/files.js
7369
+ var maxAttachedFilesPerRequest = 10;
7370
+ var attachedFilePathsSchema = array(teamStoragePathSchema).min(1).max(maxAttachedFilesPerRequest).refine((filePaths) => new Set(filePaths).size === filePaths.length, "filePaths must be unique");
7371
+ var attachedFilePathsDescription = "Paths of files in the team's storage to attach to the bug report, such as the files the bug was reproduced with. " + `At most ${maxAttachedFilesPerRequest} files, each at most 100 MB. ` + "QA Wolf keeps a copy of each file as it is now, so later changes to the original do not change the report. " + "If any path has no file, nothing is attached and the error names the path.";
7372
+ var issueFileSchema = object({
7373
+ fileId: string2().describe("The id of the attached file."),
7374
+ name: string2().describe("The file's name, taken from the last segment of the path it was attached from."),
7375
+ sizeBytes: number2().int().nonnegative()
7376
+ });
7377
+
7368
7378
  // node_modules/@qawolf/api-contracts/dist/v1/build/resource.js
7369
7379
  var buildPlatformSchema = _enum(["android", "ios"]).describe("The platform the build runs on, read from its file type.");
7370
7380
  var buildIdSchema = string2().regex(/^[a-z0-9]{24}obld$/, "Expected a build id from build.requestUpload.").describe("The id of the build, from build.requestUpload.");
@@ -8980,6 +8990,36 @@ var makeListBuildsContract = (ids) => {
8980
8990
  };
8981
8991
  };
8982
8992
 
8993
+ // node_modules/@qawolf/api-contracts/dist/v1/build/requestDownload.js
8994
+ var makeRequestBuildDownloadContract = (ids) => {
8995
+ const input = object({
8996
+ buildId: buildIdSchema,
8997
+ workspaceId: ids.workspace.optional().describe("The workspace of the build. Required when authenticating with an organization or user API key.")
8998
+ });
8999
+ const output = object({
9000
+ expiresAt: exports_iso.datetime().describe("When readUrl stops working. Request another one after it."),
9001
+ fileName: string2().describe("The name of the build's file."),
9002
+ readUrl: string2().describe('Fetch the build\'s file from here, for example `curl -o app.apk "<readUrl>"`.')
9003
+ });
9004
+ return {
9005
+ annotationJustifications: {
9006
+ destructiveHint: "Does not change the build or its file.",
9007
+ openWorldHint: "Access is limited to the build files of the authorized workspace.",
9008
+ readOnlyHint: "Returns an expiring read URL for a build's file."
9009
+ },
9010
+ annotations: {
9011
+ destructiveHint: false,
9012
+ openWorldHint: false,
9013
+ readOnlyHint: true
9014
+ },
9015
+ description: "Get a URL to download a build's file. Deleted builds can be downloaded while their file exists. Answers 404 when the file has expired.",
9016
+ input,
9017
+ kind: "read",
9018
+ name: "build.requestDownload",
9019
+ output
9020
+ };
9021
+ };
9022
+
8983
9023
  // node_modules/@qawolf/api-contracts/dist/v1/build/requestUpload.js
8984
9024
  var maxBuildFileBytes = 500 * 1024 * 1024;
8985
9025
  var makeRequestBuildUploadContract = (ids) => {
@@ -9020,6 +9060,7 @@ var makeBuildContracts = (ids) => ({
9020
9060
  delete: makeDeleteBuildContract(ids),
9021
9061
  get: makeGetBuildContract(ids),
9022
9062
  list: makeListBuildsContract(ids),
9063
+ requestDownload: makeRequestBuildDownloadContract(ids),
9023
9064
  requestUpload: makeRequestBuildUploadContract(ids)
9024
9065
  });
9025
9066
 
@@ -9627,6 +9668,7 @@ var makeGetEnvironmentVariableContract = (ids) => {
9627
9668
  });
9628
9669
  const output = object({
9629
9670
  missingNames: array(string2()).describe("Requested names the environment does not have, sorted alphabetically."),
9671
+ secretNames: array(string2()).describe("Requested names that hold write-only secrets, sorted alphabetically. Their values are never returned; flows still receive them at run time."),
9630
9672
  variables: array(object({
9631
9673
  name: string2().describe("The stored variable name."),
9632
9674
  value: string2().describe("The variable's secret value. Handle as a secret.")
@@ -9643,7 +9685,7 @@ var makeGetEnvironmentVariableContract = (ids) => {
9643
9685
  openWorldHint: false,
9644
9686
  readOnlyHint: true
9645
9687
  },
9646
- description: "Read the values of named environment variables in one call. Values are secrets. Names that do not exist go to missingNames and do not fail the call.",
9688
+ description: "Read the values of named environment variables in one call. Values are secrets. Names that do not exist go to missingNames and write-only secrets go to secretNames; neither fails the call.",
9647
9689
  input,
9648
9690
  kind: "read",
9649
9691
  name: "environment.getVariable",
@@ -10083,6 +10125,7 @@ var makeIssueResourceSchema = (ids) => resource({
10083
10125
  coveredFlowIds: array(ids.flow).describe("The flows a coverage request covers. Always empty on bug reports and blockers, whose flows are listed under reproductions."),
10084
10126
  createdAt: exports_coerce.date().describe("When the issue was created."),
10085
10127
  description: string2().describe("The issue description in Markdown."),
10128
+ files: array(issueFileSchema).default([]).describe("Files attached to a bug report, oldest first. Always empty on blockers and coverage requests."),
10086
10129
  issueId: ids.issue,
10087
10130
  name: string2(),
10088
10131
  number: number2().int(),
@@ -10340,6 +10383,34 @@ var makeAddFlowsToIssueContract = (ids) => {
10340
10383
  };
10341
10384
  };
10342
10385
 
10386
+ // node_modules/@qawolf/api-contracts/dist/v1/issue/attachFiles.js
10387
+ var makeAttachFilesToIssueContract = (ids) => {
10388
+ const input = object({
10389
+ filePaths: attachedFilePathsSchema.describe(attachedFilePathsDescription),
10390
+ issueId: ids.issue
10391
+ });
10392
+ const output = object({
10393
+ issue: makeIssueResourceSchema(ids)
10394
+ });
10395
+ return {
10396
+ annotationJustifications: {
10397
+ destructiveHint: "Adds files to the bug report without removing or replacing the ones already attached.",
10398
+ openWorldHint: "Copies files within QA Wolf storage without publishing anything outside QA Wolf.",
10399
+ readOnlyHint: "Copies files from the team's storage and attaches the copies to a bug report."
10400
+ },
10401
+ annotations: {
10402
+ destructiveHint: false,
10403
+ openWorldHint: false,
10404
+ readOnlyHint: false
10405
+ },
10406
+ description: "Attach files from the team's storage to a bug report owned by the caller's team, for example the files a bug was reproduced with. " + "Files already attached stay attached. Upload a file with file.requestUpload first.",
10407
+ input,
10408
+ kind: "write",
10409
+ name: "issue.attachFiles",
10410
+ output
10411
+ };
10412
+ };
10413
+
10343
10414
  // node_modules/@qawolf/api-contracts/dist/v1/issue/create.js
10344
10415
  var makeCreateIssueContract = (ids) => {
10345
10416
  const commonFields = {
@@ -10351,6 +10422,7 @@ var makeCreateIssueContract = (ids) => {
10351
10422
  const input = discriminatedUnion("type", [
10352
10423
  object({
10353
10424
  ...commonFields,
10425
+ filePaths: attachedFilePathsSchema.optional().describe(attachedFilePathsDescription),
10354
10426
  type: literal("bug")
10355
10427
  }),
10356
10428
  object({
@@ -10546,6 +10618,19 @@ var makeUpdateIssueContract = (ids) => {
10546
10618
  };
10547
10619
  };
10548
10620
 
10621
+ // node_modules/@qawolf/api-contracts/dist/v1/issue/contracts.js
10622
+ var makeIssueContracts = (ids) => ({
10623
+ addFlows: makeAddFlowsToIssueContract(ids),
10624
+ attachFiles: makeAttachFilesToIssueContract(ids),
10625
+ create: makeCreateIssueContract(ids),
10626
+ decideSuggestion: makeDecideSuggestionContract(ids),
10627
+ find: makeFindIssuesContract(ids),
10628
+ get: makeGetIssueContract(ids),
10629
+ listActivity: makeListIssueActivityContract(ids),
10630
+ removeFlows: makeRemoveFlowsFromIssueContract(ids),
10631
+ update: makeUpdateIssueContract(ids)
10632
+ });
10633
+
10549
10634
  // node_modules/@qawolf/api-contracts/dist/v1/legacyTrigger/resource.js
10550
10635
  var namedIdentity = object({ id: string2(), name: string2() });
10551
10636
  var branchScope = union([
@@ -10899,6 +10984,39 @@ var makeFlowFailureSchema = (ids) => {
10899
10984
  });
10900
10985
  };
10901
10986
 
10987
+ // node_modules/@qawolf/api-contracts/dist/v1/run/versions.js
10988
+ var extensibleValue = (values, meanings) => string2().describe(`One of ${values.join(", ")}; newer servers may add values, so ignore any you don't know. ${meanings}`);
10989
+ var attemptCount = number2().int().positive().describe("How many attempts reported it.");
10990
+ var runBuildVersionSchema = object({
10991
+ appId: string2().describe("The package name (Android) or bundle ID (iOS) of the app."),
10992
+ expected: object({
10993
+ buildId: buildIdSchema,
10994
+ version: string2().optional()
10995
+ }).optional().describe("The run's build of this app. Absent for an app it got none of."),
10996
+ kind: extensibleValue(["build", "info"], "build: the run got a build of this app. info: any other app an attempt installed, such as a companion app. It has no warnings."),
10997
+ observed: array(object({
10998
+ attempts: attemptCount,
10999
+ buildId: buildIdSchema.optional().describe("Absent when the file is not one of the team's builds."),
11000
+ version: string2().optional()
11001
+ })).describe("What attempts installed, one entry per build or version."),
11002
+ platform: buildPlatformSchema,
11003
+ unreportedAttempts: number2().int().nonnegative().describe("Finished attempts that reported no installed app, such as web attempts or attempts on an older Flows SDK."),
11004
+ warnings: array(extensibleValue(["changedDuringRun", "notTested", "unknownApp"], "changedDuringRun: attempts installed different builds of the run's app. notTested: attempts reported installs on this platform, but none installed the run's build. unknownApp: an attempt installed a file of this app that is not the run's build.")).describe("Why the installed apps may not be what the run should test.")
11005
+ });
11006
+ var runSiteVersionSchema = object({
11007
+ expected: object({
11008
+ from: extensibleValue(["deployment", "latestDeployment"], "deployment: the run's own deployment. latestDeployment: the environment's latest successful deployment before the run."),
11009
+ version: string2().describe("The deployed commit.")
11010
+ }).optional().describe("The commit the run should see. Only on the origin the deployment reported as its target. Absent when no deployment names a commit and a target, or the deployment has a service."),
11011
+ observed: array(object({
11012
+ attempts: attemptCount,
11013
+ source: extensibleValue(["header", "meta", "versionPath", "frameworkBuildId", "fingerprint"], "Where the attempt read the version."),
11014
+ version: string2()
11015
+ })).describe("What attempts saw, one entry per version and source."),
11016
+ origin: string2().describe("The site origin the attempts visited."),
11017
+ warnings: array(extensibleValue(["changedDuringRun", "unexpectedVersion"], "changedDuringRun: attempts saw different versions from one source. unexpectedVersion: the site served another commit than expected.")).describe("Why the site may not be the version the run should test.")
11018
+ });
11019
+
10902
11020
  // node_modules/@qawolf/api-contracts/dist/v1/run/get.js
10903
11021
  var makeGetRunContract = (ids) => {
10904
11022
  const flowStatus = _enum(publicRunStatusValues);
@@ -10925,8 +11043,10 @@ var makeGetRunContract = (ids) => {
10925
11043
  ...makeRunSummaryFields(ids),
10926
11044
  blockingBugCount: number2().int().nonnegative().describe("How many bugs this run found are blocking: still open, and priority urgent, high, or unprioritized — unprioritized counts because nobody has ruled it out yet. This is what `failed` is derived from, so it explains a failure rather than adding a second verdict: gate on `status`, then read this to say how many bugs are holding the build. It counts a bug filed against a later run by an investigation that carried over from this one, and it drops a bug once that bug is resolved."),
10927
11045
  builds: array(makeBuildResourceSchema(ids)).describe("The builds the run installs, one per app and platform. Empty when the run has none."),
11046
+ buildVersions: array(runBuildVersionSchema).describe("The apps the run's attempts installed, one per app and platform, with warnings. Empty when no attempt reported an install and the run has no builds."),
10928
11047
  flows,
10929
- runId: ids.run.describe("The run this response describes. Treat it as canonical: it can differ from the id you asked for. A deploy notification returns a run id before the run exists, and if a second notification for the same commit is folded into an earlier run, that id resolves to the earlier run instead.")
11048
+ runId: ids.run.describe("The run this response describes. Treat it as canonical: it can differ from the id you asked for. A deploy notification returns a run id before the run exists, and if a second notification for the same commit is folded into an earlier run, that id resolves to the earlier run instead."),
11049
+ siteVersions: array(runSiteVersionSchema).describe("The versions the run's attempts saw on each site origin, with warnings. Empty when no attempt reported one.")
10930
11050
  }, { urlFieldDescription: "Absolute URL of the run page." });
10931
11051
  return {
10932
11052
  annotationJustifications: {
@@ -11276,7 +11396,7 @@ var makeLaunchRunnerContract = (ids) => {
11276
11396
  openWorldHint: true,
11277
11397
  readOnlyHint: false
11278
11398
  },
11279
- description: "Launch an interactive runner on the caller's team under an id the caller chooses. Send `initialUrl` so its browser comes up on the page the work starts from, which saves a separate navigation and the browser's cold start. Launching the same id again returns the runner already running rather than starting a second one, and the same id with a different runnerName is refused. A runner is not permanent: it terminates on its own after a period of inactivity, and launching the same id after that starts and bills a new runner, so read `alreadyRunning` to tell which happened. A success means the runner is answering: the call waits for the pod it started to come up, so the very next call to the runner reaches it. If the pod does not come up in time the call fails instead, leaving the runner running, and launching the same id again attaches to it.",
11399
+ description: "Launch an interactive runner on the caller's team under an id the caller chooses. Send `initialUrl` so its browser comes up on the page the work starts from, which saves a separate navigation and the browser's cold start. Launching the same id again returns the runner already running rather than starting a second one, whatever runnerName is sent, so read `runnerName` in the answer for what is running. A runner is not permanent: it terminates on its own after a period of inactivity, and launching the same id after that starts and bills a new runner, so read `alreadyRunning` to tell which happened. A success means the runner is answering: the call waits for the pod it started to come up, so the very next call to the runner reaches it. If the pod does not come up in time the call fails instead, leaving the runner running, and launching the same id again attaches to it.",
11280
11400
  input,
11281
11401
  kind: "write",
11282
11402
  name: "runner.launch",
@@ -11424,17 +11544,14 @@ var unchangedFilesSchema = record(string2(), string2().min(1)).superRefine((hash
11424
11544
  var makeRunFlowOnRunnerContract = (ids) => {
11425
11545
  const input = object({
11426
11546
  entryPointPath: runFilePathSchema.describe("Path of the flow file to run, as it appears in `files`."),
11427
- env: runEnvironmentSchema.optional().describe("Environment variables to make available to the run."),
11428
- environmentId: ids.environmentRef.optional().describe("A QA Wolf environment whose variables the run is given, by id or alias. QA Wolf reads and decrypts them itself, so they never travel in the request and the count and length limits on `env` do not apply to them. The run also gets `QAWOLF_ENVIRONMENT_ID`, `QAWOLF_ENVIRONMENT_NAME` and `QAWOLF_TEAM_API_KEY`, as a cloud run on that environment does, so a flow can save environment variables with `@qawolf/testkit`. Send this or `env`, not both."),
11547
+ env: runEnvironmentSchema.optional().describe("Environment variables to make available to the run. With `environmentId`, they are added on top of that environment's variables for this run only, replacing any of the same name; the environment itself is not changed."),
11548
+ environmentId: ids.environmentRef.optional().describe("A QA Wolf environment whose variables the run is given, by id or alias. QA Wolf reads and decrypts them itself, so they never travel in the request and the count and length limits on `env` do not apply to them. The run also gets `QAWOLF_ENVIRONMENT_ID`, `QAWOLF_ENVIRONMENT_NAME` and `QAWOLF_TEAM_API_KEY`, as a cloud run on that environment does, so a flow can save environment variables with `@qawolf/testkit`; `env` cannot replace these three."),
11429
11549
  files: runFilesSchema.describe("Every file the run needs keyed by its path — the flow file, everything it imports, package.json and tsconfig.json. A runner holds no copy of your project, so what runs is exactly what is sent here."),
11430
11550
  flowId: ids.flow.optional().describe("The QA Wolf flow this run is for. The run then sees it as `QAWOLF_WORKFLOW_ID`, the same value a platform run of that flow sees, so fixtures named and cleaned up by it match across both. Omitted, the flow whose file is at `entryPointPath` on the named environment's flow-code branch stands in; a file not in QA Wolf yet, or a run given no environment, leaves the run with no `QAWOLF_WORKFLOW_ID`."),
11431
11551
  id: runnerIdSchema.describe("Id of the runner to run the flow on."),
11432
11552
  selection: runSelectionSchema.optional().describe("Run only these lines, inside the page the runner is already on, instead of running the whole flow from a fresh browser. Omit to run the whole entry point."),
11433
11553
  unchangedFiles: unchangedFilesSchema.optional().describe("Files this runner already holds from an earlier run, keyed by path with a hex SHA-256 of the content it should hold. Send this to make `files` only what changed. The runner refuses with `needs-full-sync` if it holds none of a referenced path, so it never runs something other than what was asked for. Omit it to send every file."),
11434
11554
  workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
11435
- }).refine((request) => request.env === undefined || request.environmentId === undefined, {
11436
- error: "Send env or environmentId, not both. An environment's variables are taken as they are stored, so there is no order in which the two would combine.",
11437
- path: ["environmentId"]
11438
11555
  }).refine((request) => Object.hasOwn(request.files, request.entryPointPath), {
11439
11556
  error: "The entry point must be one of the files.",
11440
11557
  path: ["files"]
@@ -11721,16 +11838,7 @@ var makeContractsV1 = (ids) => {
11721
11838
  update: makeUpdateFlowContract(resolvedIds)
11722
11839
  },
11723
11840
  investigation: makeInvestigationContracts(resolvedIds),
11724
- issue: {
11725
- addFlows: makeAddFlowsToIssueContract(resolvedIds),
11726
- create: makeCreateIssueContract(resolvedIds),
11727
- decideSuggestion: makeDecideSuggestionContract(resolvedIds),
11728
- find: makeFindIssuesContract(resolvedIds),
11729
- get: makeGetIssueContract(resolvedIds),
11730
- listActivity: makeListIssueActivityContract(resolvedIds),
11731
- removeFlows: makeRemoveFlowsFromIssueContract(resolvedIds),
11732
- update: makeUpdateIssueContract(resolvedIds)
11733
- },
11841
+ issue: makeIssueContracts(resolvedIds),
11734
11842
  legacyTrigger: makeLegacyTriggerContracts(resolvedIds),
11735
11843
  mcpServer: {
11736
11844
  connect: makeConnectMcpServerContract(resolvedIds)
@@ -12208,7 +12316,6 @@ var runMessages = {
12208
12316
  envFileUnparseable: (reason) => `The --env-file could not be read. ${reason}`,
12209
12317
  envFileUnreadable: (path) => `No env file at ${path}. Pass a path that exists, or drop --env-file to send no environment.`,
12210
12318
  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
12319
  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
12320
  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
12321
  filesUnreadable: (reason) => `One of the files that travel to a runner could not be read: ${reason}.`,
@@ -12235,7 +12342,9 @@ var runMessages = {
12235
12342
  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
12343
  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
12344
  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}.`
12345
+ targetMismatch: (runnerName, requiredRunnerName) => `This flow needs a ${requiredRunnerName} runner and ${runnerName} is running. Launch one with --name ${requiredRunnerName}.`,
12346
+ varMalformed: (assignment) => `--env-var takes NAME=VALUE, and "${assignment}" names no variable.`,
12347
+ varRepeated: (name) => `--env-var gives ${name} more than once, so the run's value is unclear. Pass it once.`
12239
12348
  };
12240
12349
 
12241
12350
  // src/core/messages/interactiveRunner/index.ts
@@ -16096,12 +16205,36 @@ function buildRunEnvironment(content) {
16096
16205
  ok: false
16097
16206
  };
16098
16207
  }
16099
- const checked = runEnvironmentSchema.safeParse(parsed);
16208
+ return checkRunEnvironment(parsed);
16209
+ }
16210
+ function checkRunEnvironment(environment) {
16211
+ const checked = runEnvironmentSchema.safeParse(environment);
16100
16212
  if (!checked.success) {
16101
16213
  return { error: prettifyError(checked.error), ok: false };
16102
16214
  }
16103
16215
  return { environment: checked.data, ok: true };
16104
16216
  }
16217
+ function parseRunVariables(assignments) {
16218
+ const environment = {};
16219
+ for (const assignment of assignments) {
16220
+ const separator = assignment.indexOf("=");
16221
+ const name = separator === -1 ? "" : assignment.slice(0, separator).trim();
16222
+ if (name === "") {
16223
+ return {
16224
+ error: interactiveRunnerMessages.varMalformed(assignment),
16225
+ ok: false
16226
+ };
16227
+ }
16228
+ if (Object.hasOwn(environment, name)) {
16229
+ return {
16230
+ error: interactiveRunnerMessages.varRepeated(name),
16231
+ ok: false
16232
+ };
16233
+ }
16234
+ environment[name] = assignment.slice(separator + 1);
16235
+ }
16236
+ return { environment, ok: true };
16237
+ }
16105
16238
 
16106
16239
  // src/domains/interactiveRunner/collectFiles.ts
16107
16240
  async function collectRunFiles2(deps, roots) {
@@ -16130,12 +16263,12 @@ var refused = (error, exitCode) => ({
16130
16263
  });
16131
16264
  async function prepareRun(options, deps) {
16132
16265
  const explicitEnvId = options.envId?.trim();
16133
- if (explicitEnvId !== undefined && options.envFile !== undefined) {
16134
- return refused(interactiveRunnerMessages.envIdWithEnvFile, exitCodes.invalidArgs);
16135
- }
16136
16266
  if (explicitEnvId === "") {
16137
16267
  return refused(interactiveRunnerMessages.envIdBlank, exitCodes.invalidArgs);
16138
16268
  }
16269
+ const fromVars = parseRunVariables(options.vars);
16270
+ if (!fromVars.ok)
16271
+ return refused(fromVars.error, exitCodes.invalidArgs);
16139
16272
  const fromEnvVar = deps.env["QAWOLF_ENVIRONMENT"]?.trim();
16140
16273
  const environmentId = explicitEnvId ?? (options.envFile === undefined && fromEnvVar ? fromEnvVar : undefined);
16141
16274
  const linesFilePath = options.linesFile === undefined ? undefined : toCollectedPath(deps.cwd, options.linesFile);
@@ -16148,11 +16281,18 @@ async function prepareRun(options, deps) {
16148
16281
  if (check.type !== "ok") {
16149
16282
  return refused(describeRunFilesCheck(check), exitCodes.invalidArgs);
16150
16283
  }
16151
- const environment = await readEnvironment(options.envFile, deps);
16152
- if (environment !== undefined && !environment.ok) {
16153
- return refused(environment.error, exitCodes.config);
16284
+ const fromFile = await readEnvironment(options.envFile, deps);
16285
+ if (fromFile !== undefined && !fromFile.ok) {
16286
+ return refused(fromFile.error, exitCodes.config);
16287
+ }
16288
+ const combined = fromFile === undefined && options.vars.length === 0 ? undefined : checkRunEnvironment({
16289
+ ...fromFile?.environment,
16290
+ ...fromVars.environment
16291
+ });
16292
+ if (combined !== undefined && !combined.ok) {
16293
+ return refused(combined.error, exitCodes.invalidArgs);
16154
16294
  }
16155
- const given = environment?.ok === true ? environment.environment : undefined;
16295
+ const given = combined?.environment;
16156
16296
  if (options.lines === undefined) {
16157
16297
  return options.linesFile === undefined ? {
16158
16298
  environment: given,
@@ -16379,7 +16519,8 @@ function createRunVerbs({ deps, platformClient }) {
16379
16519
  envFile: undefined,
16380
16520
  envId: environment === "ambient" ? undefined : environment.id,
16381
16521
  lines: toLineRange(selection),
16382
- linesFile: toLinesFile(selection)
16522
+ linesFile: toLinesFile(selection),
16523
+ vars: []
16383
16524
  }, deps);
16384
16525
  if (!prepared.ok)
16385
16526
  return { error: prepared.error, ok: false };
@@ -16474,4 +16615,4 @@ export {
16474
16615
  createRunnerSdk
16475
16616
  };
16476
16617
 
16477
- //# debugId=87F77F3A03400AEC64756E2164756E21
16618
+ //# debugId=75C8CC52E0AB71DC64756E2164756E21
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qawolf/cli",
3
- "version": "2.4.0",
3
+ "version": "2.6.0",
4
4
  "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
5
5
  "keywords": [
6
6
  "automation",
@@ -72,7 +72,7 @@
72
72
  "@clack/prompts": "1.5.1",
73
73
  "@napi-rs/keyring": "1.3.0",
74
74
  "@oxc-node/core": "0.1.0",
75
- "@qawolf/api-contracts": "0.104.0",
75
+ "@qawolf/api-contracts": "0.107.0",
76
76
  "@qawolf/emails": "1.1.1",
77
77
  "@qawolf/flow-targets": "2.0.0",
78
78
  "@qawolf/flows": "0.3.0",
@@ -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.
@@ -146,6 +148,7 @@ that `url`; never guess a route and never send a repository link in its place.
146
148
  | `qawolf build delete` | write | Delete a build. Runs never install a deleted build. Deleting an environment's latest build makes the previous one its latest. Runs install that build only if its file is still kept: only the latest builds of static environments are kept past the bucket's expiry, 180 days after upload on QA Wolf's cloud. Answers the build with deletedAt set. Deleting a deleted build answers it unchanged. |
147
149
  | `qawolf build get` | read | Get a build: its app, platform, version and environment. Deleted builds are returned too. |
148
150
  | `qawolf build list` | read | List the workspace's undeleted builds, newest first. With latestOnly, list what the environment's next run installs. |
151
+ | `qawolf build requestDownload` | read | Get a URL to download a build's file. Deleted builds can be downloaded while their file exists. Answers 404 when the file has expired. |
149
152
  | `qawolf build requestUpload` | write | Get a URL to upload an app build: an .apk, .aab or .ipa, up to 500 MB. PUT the file there with uploadHeaders, then call build.create with the buildId. |
150
153
  | `qawolf codeHostIntegration find` | read | List the workspace's code host integrations (GitHub or GitLab). A connected integration lets QA Wolf read repositories and receive the code host's webhooks. codeHostIntegration.listRepositories pages the repositories each integration covers. |
151
154
  | `qawolf codeHostIntegration listRepositories` | read | List the repositories the workspace's code host integrations cover, alphabetical by full name. The list reflects the last sync from the code host; codeHostIntegration.find lists the integrations themselves. |
@@ -163,7 +166,7 @@ that `url`; never guess a route and never send a repository link in its place.
163
166
  | `qawolf environment deleteVariable` | write | Remove one environment variable by name. Succeeds whether or not the variable existed. |
164
167
  | `qawolf environment find` | read | List the team's environments, newest first. |
165
168
  | `qawolf environment get` | read | Read a single environment's name, kind, release readiness status, flow-code branch and reconciliation state, run concurrency limit, and termination state. If flowCodeBranch exists, use its syncStatus for Git reconciliation and read lastSyncedCommitHash only when syncStatus is reconciled. |
166
- | `qawolf environment getVariable` | read | Read the values of named environment variables in one call. Values are secrets. Names that do not exist go to missingNames and do not fail the call. |
169
+ | `qawolf environment getVariable` | read | Read the values of named environment variables in one call. Values are secrets. Names that do not exist go to missingNames and write-only secrets go to secretNames; neither fails the call. |
167
170
  | `qawolf environment listVariableNames` | read | Use this to answer which QA Wolf environment variables are available to test code. Returns names only; values never leave the server. |
168
171
  | `qawolf environment promote` | write | Declare a preview environment's work accepted, typically when its pull request merges: its flow changes are promoted into its base environment and the environment is terminated once they land. Returns the promotion in pending; poll promotion.get to learn how it settled. Calling again while a promotion is open returns that promotion. A conflict settles the promotion conflicted and cancels the environment's in-progress runs; promotion.get names the conflicting paths. Use environment.terminate instead when the work is abandoned. |
169
172
  | `qawolf environment setVariable` | write | Create or replace an environment variable. If the user asks to create one for "my email" without naming it, use DEFAULT_EMAIL. The value is never returned. |
@@ -186,6 +189,7 @@ that `url`; never guess a route and never send a repository link in its place.
186
189
  | `qawolf investigation get` | read | Read what the QA Wolf AI investigating a run has concluded: one finding per cause of its failures, with the question waiting for a person and any answer or dispute the investigation hasn't acted on yet. A run that automatic investigation does not cover answers status "not-enabled". |
187
190
  | `qawolf investigation question find` | read | List the questions the QA Wolf AI investigating failed runs is waiting for a person to answer, across a workspace's runs. Each question names its run, flows, details and offered answers. To answer one, send the person's answer to its sessionId with agent.send. |
188
191
  | `qawolf issue addFlows` | write | Add flows to a coverage request owned by the caller's team. Flows already covered stay covered. Bug reports and blockers link to flows through the runs that reproduce them; use run.diagnose to record one. |
192
+ | `qawolf issue attachFiles` | write | Attach files from the team's storage to a bug report owned by the caller's team, for example the files a bug was reproduced with. Files already attached stay attached. Upload a file with file.requestUpload first. |
189
193
  | `qawolf issue create` | write | Create a bug report, blocker (issue type `maintenance`), or coverage request issue for the caller's team. A user can create a blocker only when they can see the workspace's blockers; a team or organization API key credits it to the workspace's automation user. Link its failed flows afterwards with run.diagnose. |
190
194
  | `qawolf issue decideSuggestion` | write | Decide a coverage request or bug report that QA Wolf suggested after exploring an environment. Add turns on the suggested flow in the environment. Report files a potential bug. Skip declines the suggestion. Undo takes back a decision before the flow joins. The issue's status follows the decision, so change the status only through this tool while the suggestion is undecided. |
191
195
  | `qawolf issue find` | read | List the team's bug reports, blockers, or coverage requests, newest first. |
@@ -207,6 +207,17 @@ Every documented field of the `run.get` response. `[]` marks an array, so
207
207
  - `builds[].sizeBytes` — The file's size in bytes.
208
208
  - `builds[].version` — versionName (Android) or CFBundleShortVersionString (iOS), when the file has one.
209
209
  - `builds[].url` — Absolute URL of the team's Builds page.
210
+ - `buildVersions` — The apps the run's attempts installed, one per app and platform, with warnings. Empty when no attempt reported an install and the run has no builds.
211
+ - `buildVersions[].appId` — The package name (Android) or bundle ID (iOS) of the app.
212
+ - `buildVersions[].expected` — The run's build of this app. Absent for an app it got none of.
213
+ - `buildVersions[].expected.buildId` — The id of the build, from build.requestUpload.
214
+ - `buildVersions[].kind` — One of build, info; newer servers may add values, so ignore any you don't know. build: the run got a build of this app. info: any other app an attempt installed, such as a companion app. It has no warnings.
215
+ - `buildVersions[].observed` — What attempts installed, one entry per build or version.
216
+ - `buildVersions[].observed[].attempts` — How many attempts reported it.
217
+ - `buildVersions[].observed[].buildId` — Absent when the file is not one of the team's builds.
218
+ - `buildVersions[].platform` — One of: android, ios
219
+ - `buildVersions[].unreportedAttempts` — Finished attempts that reported no installed app, such as web attempts or attempts on an older Flows SDK.
220
+ - `buildVersions[].warnings` — Why the installed apps may not be what the run should test.
210
221
  - `flows` — The run's flows, ordered alphabetically by name. Only the flows matching flowStatuses when the request set it.
211
222
  - `flows[].attempts` — The flow's finished execution attempts, oldest first, including manual Wolf Browser attempts. Present once at least one attempt has finished, so a flow that passed after retries also lists its failed attempts. Artifact URLs appear only on attempts that reached a verdict, and on a manual attempt only when its Wolf Browser run kept them. They stay valid for at least a day (call run.get again for fresh ones), and can return 404 when the attempt did not produce that artifact.
212
223
  - `flows[].attempts[].logsUrl` — Signed URL for the attempt's execution logs.
@@ -225,6 +236,15 @@ Every documented field of the `run.get` response. `[]` marks an array, so
225
236
  - `flows[].failure.optedOutOfInvestigation.by` — One of: user, system
226
237
  - `flows[].flowId` — The id of the flow.
227
238
  - `flows[].status` — One of: failed, queued, running, passed, canceled
239
+ - `siteVersions` — The versions the run's attempts saw on each site origin, with warnings. Empty when no attempt reported one.
240
+ - `siteVersions[].expected` — The commit the run should see. Only on the origin the deployment reported as its target. Absent when no deployment names a commit and a target, or the deployment has a service.
241
+ - `siteVersions[].expected.from` — One of deployment, latestDeployment; newer servers may add values, so ignore any you don't know. deployment: the run's own deployment. latestDeployment: the environment's latest successful deployment before the run.
242
+ - `siteVersions[].expected.version` — The deployed commit.
243
+ - `siteVersions[].observed` — What attempts saw, one entry per version and source.
244
+ - `siteVersions[].observed[].attempts` — How many attempts reported it.
245
+ - `siteVersions[].observed[].source` — One of header, meta, versionPath, frameworkBuildId, fingerprint; newer servers may add values, so ignore any you don't know. Where the attempt read the version.
246
+ - `siteVersions[].origin` — The site origin the attempts visited.
247
+ - `siteVersions[].warnings` — Why the site may not be the version the run should test.
228
248
  - `url` — Absolute URL of the run page.
229
249
 
230
250
  <!-- fields:end -->
@@ -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