WisentProbierz
Probierz/Docs

CLI command

probierz run

Execute one target, capture supported evidence, and analyze its report.

Invocation#

Shell
probierz run <TARGET> [ARGS]...

Options from source help#

run opts
NAME=VALUE            Environment variable given to the suite; repeatable
  --app <ID>            Application manifest whose surface and secrets apply
  --spec <FILE>         One spec file instead of the target's whole suite
  --tool <NAME>         Report shape to expect: wdio or probierz
  --record              Keep video, traces, and screenshots for every journey
  --force               Run even when the resource this target locks is held
  --no-analyze          Skip report analysis and print the raw run
  --no-repair           Do not offer an authored repair for a failed run
  --frames <N>          Frames to extract, spread across each recording; none unless given
  --files <PATH>...     Changed files that select what runs (affected, ci)

Required inputs and options#

  • `<target>` is required and is one of web | mobile:ios | mobile:android | desktop:mac | desktop:win | desktop:cua | tui, `first-use/<appId>`, or `suites/<checkout>`.
  • `--app <appId>` selects the registered product whose manifest and source identity belong to the run.
  • `--record` requests supported video, trace, and screenshot capture; `--force` runs even when the resource this target locks is held.
  • `--spec <path>` narrows execution to one spec. An absolute path may name an application-owned program in its own repository; its report records `owner: "application"`. `--frames N` extracts N frames spread across each recording; none are extracted unless it is given, in a plan or on the command line. `--tool wdio|probierz` names the report shape to expect.
  • `--no-analyze` suppresses automatic report analysis; `--no-repair` does not offer an authored repair for a failed run.
  • Trailing `KEY=VALUE` arguments become the target process environment.
  • `first-use/<appId>` plays that product's first-use journey as a new user and takes no further arguments. The product manifest declares it under `firstUse:` — `definition` (the product's first-use definition), `install` (its public install instructions, one argv each), `path` (where the installed program lands under the new home), `fixtures` (the user's own data for each placeholder a screen shows, such as `PATH`) and `progress` (`file` under the home and the JSON-pointer `fact` where the product records first success).
  • `suites/<checkout> [<gate>...]` runs the test suites the checkout's release manifest declares for this platform (see `probierz check suites/<checkout>`): the named gates, or every declared one in manifest order.

Output and state effects#

Runs the selected surface and writes the completed run and analysis as JSON. A preflight-blocked run prints its skipped result and fails with code `prerequisite` (exit 1); a run skipped because another run holds the resource lock fails with code `unavailable` (exit 75, worth retrying); a completed non-passing run exits 1; only completed runs are analyzed. A first-use run gets a clean home under `test-results/<appId>/first-use/<started>/` with only `PATH` inherited, runs every install step, walks the definition's screens from `entry_screen_id` and runs the command each one shows with the fixtures in place of its placeholders, then reads the product's own progress record. It prints and keeps `record.json` (every step's argv, exit and output files, the analytics events reached, and `firstSuccess` with the expected and observed value) and passes only when the product recorded the first-success fact with the value the definition expects. A suites run reads the checkout's revision and dirty paths from Git, then runs each gate's argv in the checkout with stdin closed and both streams on files, waiting for it to its own end, and keeps the run under `test-results/.suites/<product>/<started>-<short revision>/`: `run.json` (`ai.wisent.probierz.suite-run.v1`: product, source revision and dirty paths, start and finish, every gate's argv, exit code or process error, duration when started, stream paths, and each declared report as copied, absent, or failed with the source/destination and I/O cause) beside each gate's streams and copied reports. A gate that cannot set up its streams or finish waiting remains a failed gate in the run record, preserving other gates; a report that exists but cannot be copied fails its gate without losing the process exit status or earlier report outcomes. The CLI prints the record; a run with any failed gate exits 1 and names the kept directory.

Exact refusals#

  • Missing target: `run needs a target (one of …)`; unknown target: `unknown target: <target>`.
  • Unknown options (`unknown option: <option>`), unexpected positional values, missing option values (`<flag> needs a value`), and negative frame counts are refused.
  • Preflight refusal returns a structured skipped result instead of spawning the target unless `--force` is explicit.
  • first-use: a manifest without `firstUse:`, an unknown or missing key, an empty install argv, a progress file or path entry outside the home, a fact that is not a JSON pointer, or an unreadable definition is refused with code `config` naming the manifest; a definition whose path branches, loops or names a missing screen, or a placeholder with no fixture, is refused naming the screen; an argument after the target is refused; a journey that ran but did not reach first success fails with code `refused` naming the record.
  • suites: every manifest refusal of `probierz check suites/<checkout>`; `<manifest> declares no test gate for this platform; declare each suite as a quality gate of kind "test"`; `no test gate named <name>; declared: <names>`; `<checkout> is not a checkout this host can open: <error>`; `git <args> could not run in <checkout>: <error>` and `git <args> in <checkout> ended with <status>: <stderr>`; a run directory already taken is refused rather than reused; a gate whose program cannot start, whose streams cannot be opened, whose process cannot be waited for, or whose declared report cannot be copied is recorded with its operation and cause and fails the run. A symbolic link in a report path or copied tree is refused with its path; other gates and earlier report outcomes remain in the kept record. Failure to write `run.json` is a storage error naming that file, not a completed run.

Source snapshot#

Generated from the Rust binaries at https://github.com/wisent-ai/probierz.git revision `f65b755da397f2ec7435eb80ed722aa6017437c1`.

Combined help SHA-256: `4a12655d233812abc29eeebbf3db3065efe3e00288024383f3eef3970d092e94`; binary SHA-256: `d5398832d3ab52c541b1efe979730dea62941ac6197898a20fccfc5d3fca44df`.