@qawolf/cli 1.34.0 → 1.36.0

package/dist/types/runnerSdk/types.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserAction, InspectOnRunnerRequest, JournalStream, PublicApiInput, PublicApiOutput, ReadJournalResponse, RunnerNameForPublicApi, publicContractsV1 } from "@qawolf/api-contracts/v1";
+import type { InspectOnRunnerRequest, JournalStream, PublicApiInput, PublicApiOutput, ReadJournalResponse, RunnerAction, RunnerNameForPublicApi, publicContractsV1 } from "@qawolf/api-contracts/v1";
 type Runner = typeof publicContractsV1.runner;
 export type RunnerSdkOptions = {
     /** A QA Wolf team API key. The SDK never reads the CLI's stored credentials. */
@@ -77,7 +77,7 @@ export type EventsRequest = RunnerRequest & {
     window: JournalWindow;
 };
 export type ActRequest = RunnerRequest & {
-    action: BrowserAction;
+    action: RunnerAction;
     /**
      * Ask the runner to answer with a screenshot taken after the action, on
      * `imageJpegBase64`. One call instead of an act and a screenshot, with no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.34.0",
+  "version": "1.36.0",
   "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   "keywords": [
     "automation",
@@ -71,7 +71,7 @@
     "@clack/prompts": "1.5.1",
     "@napi-rs/keyring": "1.3.0",
     "@oxc-node/core": "0.1.0",
-    "@qawolf/api-contracts": "0.64.0",
+    "@qawolf/api-contracts": "0.73.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",

package/skills/qawolf-cli/SKILL.md

@@ -76,7 +76,9 @@ sequence, omit it when you want the payloads themselves.
 
 A `--json` response shows you most of its own shape, so read it first.
 
-`qawolf run get` is the exception worth reading about before you use it. Its
+`qawolf run get` is the exception worth reading about before you use it. A
+suite run can hold hundreds of flows, so start with
+`--flow-statuses failed` and widen only if you need the rest. Its
 artifact URLs expire, its failure fields are absent from a passing run, and its
 `traceUrl` downloads a Playwright trace that you can read as JSON without
 opening the trace viewer. **Read
@@ -164,8 +166,9 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf install android` | local | Install Android system images, AVDs, and the Appium driver used by the project's Android flows |
 | `qawolf install browsers` | local | Install Playwright browsers used by the project's web flows |
 | `qawolf install clear` | local | Remove the managed runtime cache (all installed runtime versions) |
+| `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. |
 | `qawolf issue addFlows` | write | Add flows to a coverage request owned by the caller's team. Flows already covered stay covered. Bug and maintenance reports link to flows through the runs that reproduce them; use run.diagnose to record one. |
-| `qawolf issue create` | write | Create a bug or coverage request issue for the caller's team. Maintenance issues cannot be created through the public API. |
+| `qawolf issue create` | write | Create a bug report, maintenance report, or coverage request issue for the caller's team. A user can create a maintenance report only when they can see the workspace's maintenance reports; a team or organization API key credits it to the workspace's automation user. Link its failed flows afterwards with run.diagnose. |
 | `qawolf issue find` | read | List the team's bug reports, maintenance reports, or coverage requests, newest first. |
 | `qawolf issue get` | read | Get an issue by id. |
 | `qawolf issue removeFlows` | write | Remove flows from a coverage request owned by the caller's team. Flows the request does not cover are left alone. Bug and maintenance reports link to flows through the runs that reproduce them, so their flows cannot be set directly. |
@@ -176,11 +179,10 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf run create` | write | Create a run for the selected flows and/or tags in an environment. |
 | `qawolf run diagnose` | write | Diagnose failed flows in a run as reproductions of a bug or maintenance report owned by the caller's team. The issue's type selects the diagnosis. Each flow must have failed in the run. A flow that is already diagnosed moves to this issue. The diagnosis appears on the run, and the reproduction appears under the issue's reproductions. Coverage requests cannot be diagnosed; use issue.addFlows to cover flows instead. |
 | `qawolf run find` | read | List an environment's recent runs, newest first. |
-| `qawolf run get` | read | Get a run's status, per-flow results, and links. |
+| `qawolf run get` | read | Get a run's status, per-flow results, links, and how many of its bugs are blocking. |
 | `qawolf run reattempt` | write | Request new attempts for a run's flows, in the same run. A flow is eligible once its result is failed or canceled and QA Wolf's automatic retries have finished. A fully investigated run no longer accepts reattempts. Attempts run with the latest flow code. Poll run.get for results. |
 | `qawolf run stop` | write | Stop a run, including its queued flows and automatic retries. Stopping is asynchronous and can update run-status messages and commit statuses in connected integrations. Repeated requests are safe, and finished runs keep their results. A run that is still being created returns not found; retry once run.get returns the run. If run.get returns a different runId, use that ID. Poll run.get for results. |
-| `qawolf run triage` | read | Prototype. Ask Jev, a TypeSafe System One model, whether a flow failure in a run is a bug in the product or a test that needs maintenance. Compares the failing attempt with the flow's last passing run in the same environment. Records nothing. |
-| `qawolf runner act` | write | Perform one raw action on a runner's screen: click, double_click, scroll, move, drag, keypress, navigate or type. Use - to read a whole action as JSON from stdin. On a mobile runner only click (button left), drag and type have a touchscreen equivalent; the rest answer action-not-supported-on-mobile |
+| `qawolf runner act` | write | Perform one raw action on a runner's screen. A browser runner takes click, double_click, scroll, move, drag, keypress, navigate and type; a mobile runner takes tap, swipe, fill and type. A browser runner answers mobile actions with action-not-supported-on-browser; a mobile runner answers the other browser actions with action-not-supported-on-mobile. Use - to read a whole action as JSON from stdin |
 | `qawolf runner actions` | write | Perform a sequence of up to ten raw actions on a runner's screen in one request, as a JSON array of the same actions `runner act` takes. Use - to read the array from stdin. Actions run back to back, so batch only steps whose targets are on the screen you last saw, and end the sequence at the step that changes the page. Each result carries an effect: performed, not-performed, or unknown when the runner stopped answering and the action may have landed |
 | `qawolf runner events` | read | Print a runner's journal, one entry per line. QA Wolf writes console, recorder, run-events, run-logs, run-status |
 | `qawolf runner exec` | write | Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin |

package/skills/qawolf-cli/references/run-results.md

@@ -8,6 +8,32 @@ this file for the parts a single response cannot show you: fields that appear
 only when something fails, rules about the artifact URLs, and how to read a
 trace without opening the trace viewer.
 
+## Start with the failed flows
+
+A run of a whole suite can hold hundreds of flows, and the full response then
+runs to hundreds of kilobytes: more than a shell shows you, and more than any
+investigation needs. The interesting part is a handful of failed flows, so ask
+for those first:
+
+```bash
+qawolf run get --run-id "$RUN_ID" --flow-statuses failed --json
+```
+
+`--flow-statuses` takes one or more of `queued`, `running`, `passed`, `failed`
+and `canceled`, separated by spaces (`--flow-statuses failed canceled`), and
+keeps only the flows whose status matches. The run-level fields (`status`,
+`blockingBugCount`, `git`, `url`) still describe the whole run, so a filtered
+read tells you both how the run went and which flows to look at. Widen the
+filter, or drop it, only when you need the other flows too.
+
+A flow that failed and then passed on a retry has status `passed`, so a
+`failed`-only read leaves it out. If the flow you were asked about passed on a
+retry, add `passed` to the filter and read its earlier attempts. For a flow
+that is still queued, running or was canceled, widen the filter or drop it.
+
+Do not save the full response to a file and script over it to find the failed
+flows. The filter answers that in one call.
+
 ## The shape
 
 A run holds flows, a flow holds attempts, and artifacts hang off an attempt:
@@ -63,7 +89,7 @@ recording) and `traceUrl` (a Playwright `trace.zip`).
    authentication header is needed and no QA Wolf credentials are involved.
 
 ```bash
-qawolf run get --run-id "$RUN_ID" --json \
+qawolf run get --run-id "$RUN_ID" --flow-statuses failed --json \
   | jq -r '.flows[].attempts[-1].traceUrl // empty' \
   | head -1 \
   | xargs -r curl -sS -o trace.zip
@@ -157,9 +183,11 @@ Every documented field of the `run.get` response. `[]` marks an array, so
 - `completedAt` — When the run finished executing. Absent while queued or running, and also absent for a terminal run that never completed execution (e.g. every flow was canceled or skipped).
 - `git` — The branch and commit under test. The fields are present when a deploy notification started the run, and absent for runs started another way, for example manually or with run.create.
 - `git.commitUrl` — Link to the commit on the code host.
+- `needsReview` — True once every flow has finished its attempts and at least one failed flow still has no diagnosis, including one whose investigation carried over to a later run. `status` stays `running` until that failure is diagnosed, so a caller that is not waiting for a diagnosis can stop polling here and read the run's failed flows.
 - `runId` — 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.
 - `status` — One of: queued, running, passed, failed, canceled
-- `flows` — The run's flows, ordered alphabetically by name.
+- `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.
+- `flows` — The run's flows, ordered alphabetically by name. Only the flows matching flowStatuses when the request set it.
 - `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 automated attempts that reached a verdict, 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.
 - `flows[].attempts[].logsUrl` — Signed URL for the attempt's execution logs.
 - `flows[].attempts[].traceUrl` — Signed URL for the attempt's Playwright trace (a trace.zip; open it with `npx playwright show-trace`).

package/skills/qawolf-cli/references/runner.md

@@ -126,7 +126,7 @@ Retry on the exit code, not on the message text:
   launch the id or name one that is running. The message says which runner was
   meant and whether `--runner`, `QAWOLF_RUNNER_ID` or this directory's stored
   default chose it — read that line before you pick an id to launch.
-- `2` will not clear on its own. Nothing has run on this runner yet, so run a flow; or the runner has no browser at all, so launch with `--name playwright` instead; or the action has no touchscreen equivalent on a mobile runner, so reach for one that has. A `runner actions` sequence also exits `2` before it sends anything, for an argument that is not a JSON array, an array of more than ten actions, and `--screenshot` flags that contradict each other. The message says which.
+- `2` will not clear on its own. Nothing has run on this runner yet, so run a flow; or the runner has no browser at all, so launch with `--name playwright` instead; or the action belongs to the other runner family, so send `tap`, `swipe` or `fill` to a mobile runner and the browser actions to a browser runner. A `runner actions` sequence also exits `2` before it sends anything, for an argument that is not a JSON array, an array of more than ten actions, and `--screenshot` flags that contradict each other. The message says which.
 
 ## Seeing and acting: the loop is yours
 
@@ -167,17 +167,18 @@ Coordinates are pixels on the same screenshot you just read. The runner serves o
 
 `act`, `actions`, `run` and `exec` are the commands whose lost answer may still have taken effect. On a `4` from `act` or `actions`, take a screenshot before repeating a click. `exec`'s message says the snippet could not be evaluated, but a lost answer looks the same from outside, so treat a `4` from a snippet that changes something as "may have run" rather than "did not run".
 
-A mobile runner has a touchscreen, not a mouse, so only three of the eight
-actions have a touchscreen equivalent and go through: `click` with
-`button: "left"` taps, `drag` swipes, and `type` types into whatever the last
-tap focused. The rest — `double_click`, `scroll`, `move`, `keypress`,
-`navigate` — answer `action-not-supported-on-mobile` rather than doing
-something approximate. `navigate` is the one to watch for, since it works on a
-browser runner without a run first but has no meaning on mobile at all.
+A mobile runner has a touchscreen, not a mouse, so it has actions of its own:
+
+- `tap` touches a point (`--x`, `--y`) or the element `--selector` names. Check the selector first with `inspect elements --selector`, and pass `--strategy ios-predicate` or `shadow` when it is not XPath.
+- `swipe --from x,y --to x,y` moves in a straight line between two points. `--duration-ms` sets how long it takes, up to 10000: a slow swipe scrolls, a fast one flings.
+- `fill --selector ... --text ...` replaces the value of that field, and `--text ""` clears it. To add to what a field already holds, `tap` it and then `type`.
+- `type` types into whatever the last tap focused, the same as on a browser.
+
+The browser actions `double_click`, `scroll`, `move`, `keypress` and `navigate` answer `action-not-supported-on-mobile` rather than doing something approximate. `navigate` is the one to watch for, since it works on a browser runner without a run first but has no meaning on mobile at all. `click` with `button: "left"` and `drag` still tap and swipe on mobile, but they are deprecated there, so send `tap` and `swipe`. A browser runner answers `tap`, `swipe` and `fill` with `action-not-supported-on-browser`.
 
 ### Several steps in one request: `runner actions`
 
-`qawolf runner actions '<json array>'` performs up to ten of those same actions back to back in one request, for the steps you already know: click the field, type into it, press Enter. One round trip instead of three, with no delay to guess at between them, and `-` reads the array from stdin the way `act -` reads one action.
+`qawolf runner actions '<json array>'` performs up to ten of the browser actions back to back in one request (not `tap`, `swipe` or `fill`), for the steps you already know: click the field, type into it, press Enter. One round trip instead of three, with no delay to guess at between them, and `-` reads the array from stdin the way `act -` reads one action.
 
 ```sh
 qawolf runner actions '[{"type":"click","button":"left","x":480,"y":260},{"type":"type","text":"me@example.com"},{"type":"keypress","keys":["Enter"]}]' --screenshot after-login.jpg