@qawolf/cli 2.3.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qawolf/cli",
3
- "version": "2.3.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",
@@ -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.98.1",
75
+ "@qawolf/api-contracts": "0.104.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.
@@ -142,6 +144,11 @@ that `url`; never guess a route and never send a repository link in its place.
142
144
  | `qawolf auth logout` | local | Remove stored credentials |
143
145
  | `qawolf auth switch` | local | Choose which workspace to work in |
144
146
  | `qawolf auth whoami` | read | Show authentication status |
147
+ | `qawolf build create` | write | Create a build from a file uploaded with build.requestUpload. Reads the app ID, name, version and build number from the file before it answers, or refuses a file that isn't an app. Calling it again with the same buildId answers the build the first call created, unchanged: a repeated call's branch, commitSha and environment are ignored. |
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. |
149
+ | `qawolf build get` | read | Get a build: its app, platform, version and environment. Deleted builds are returned too. |
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 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. |
145
152
  | `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. |
146
153
  | `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. |
147
154
  | `qawolf deployment find` | read | List the deployments QA Wolf has received for the workspace, newest first. A deployment arrives through a code host integration's webhook or through deployment.reportStatus, and is what a deployment trigger evaluates against. deployment.listTriggerEvaluations reports each trigger's verdict for one deployment. |
@@ -179,8 +186,10 @@ that `url`; never guess a route and never send a repository link in its place.
179
186
  | `qawolf install browsers` | local | Install Playwright browsers used by the project's web flows |
180
187
  | `qawolf install clear` | local | Remove the managed runtime cache (all installed runtime versions) |
181
188
  | `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". |
189
+ | `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. |
182
190
  | `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. |
183
191
  | `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. |
192
+ | `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. |
184
193
  | `qawolf issue find` | read | List the team's bug reports, blockers, or coverage requests, newest first. |
185
194
  | `qawolf issue get` | read | Get an issue by id. |
186
195
  | `qawolf issue listActivity` | read | List an issue's activity, oldest first: creation, status and priority changes, and the flows that started or stopped reproducing it. Use it to measure time to fix or to find issues that came back. |
@@ -189,6 +198,7 @@ that `url`; never guess a route and never send a repository link in its place.
189
198
  | `qawolf legacyTrigger find` | read | List a workspace's legacy per-environment triggers; trigger.find lists the current ones. For migration only; it goes when legacy triggers go. adaptiveFlowSelection becomes a generativeSuite action, which takes no tags. |
190
199
  | `qawolf legacyTrigger pause` | write | Pause one legacy trigger, the older per-environment kind, so it stops firing; use trigger.pause for a current one. Its copies in pull request environments pause too. For migration only; it goes when legacy triggers go. |
191
200
  | `qawolf legacyTrigger resume` | write | Resume one legacy trigger, the older per-environment kind; use trigger.resume for a current one. Its copies in pull request environments resume too, and a scheduled one jumps to the next upcoming slot even if it was not paused. For migration only; it goes when legacy triggers go. |
201
+ | `qawolf mcpServer connect` | write | Start connecting an MCP server from the workspace's catalog, such as Linear, so Tester can use its tools. Returns a sign-in link to show the user. |
192
202
  | `qawolf promotion find` | read | List environment promotions, newest first. A promotion moves the flow changes made in a head environment into its base environment. Filter by status conflicted to find the promotions whose conflicts still need a resolution. |
193
203
  | `qawolf promotion get` | read | Read one environment promotion: its status, the conflicting paths and commit hashes while it is conflicted or resolving, the commit it landed when promoted, and the AI task resolving it. Poll it after environment.promote to learn how the promotion settled. It does not serve file contents; a resolver reads both branches from the flow code repository. |
194
204
  | `qawolf promotion resolve` | write | Submit the resolution of a conflicted promotion: the full resolved contents of every conflicting path to keep, and every conflicting path to delete. Together they must cover exactly the paths in the promotion's conflict, and both commit hashes must match the conflict's; if a branch moved since, the call is refused as stale-conflict and promotion.get has the current conflict. Returns the promotion in resolving; poll promotion.get until it is promoted, or conflicted again if the branches moved while it applied. |
@@ -192,6 +192,21 @@ Every documented field of the `run.get` response. `[]` marks an array, so
192
192
  - `supersededBy.runId` — The id of the run.
193
193
  - `supersededBy.url` — Absolute URL of the replacement run's page.
194
194
  - `blockingBugCount` — 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.
195
+ - `builds` — The builds the run installs, one per app and platform. Empty when the run has none.
196
+ - `builds[].appId` — The package name (Android) or bundle ID (iOS) read from the file. A flow launches it with `launch({ app: { id } })`.
197
+ - `builds[].appName` — The app's display name, when the file names one.
198
+ - `builds[].branch` — The branch the uploader said the build came from.
199
+ - `builds[].buildNumber` — versionCode (Android) or CFBundleVersion (iOS), when the file has one.
200
+ - `builds[].commitSha` — The commit the uploader said the build came from.
201
+ - `builds[].createdAt` — When the build was created.
202
+ - `builds[].deletedAt` — When the build was deleted. Runs never install it after.
203
+ - `builds[].environmentId` — The environment whose runs install the build while it is the newest one there for its app and platform. Absent: only a run created with the build installs it.
204
+ - `builds[].fileName` — The uploaded file's name.
205
+ - `builds[].id` — The id of the build, from build.requestUpload.
206
+ - `builds[].platform` — One of: android, ios
207
+ - `builds[].sizeBytes` — The file's size in bytes.
208
+ - `builds[].version` — versionName (Android) or CFBundleShortVersionString (iOS), when the file has one.
209
+ - `builds[].url` — Absolute URL of the team's Builds page.
195
210
  - `flows` — The run's flows, ordered alphabetically by name. Only the flows matching flowStatuses when the request set it.
196
211
  - `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.
197
212
  - `flows[].attempts[].logsUrl` — Signed URL for the attempt's execution logs.
@@ -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