WisentProbierz
Probierz/Docs

Journeys, discovery, and runs.

Journeys are defined once in application manifests and executed across the supported surfaces. Discovery is strictly read-only; execution is preflight-gated and produces durable, analyzable artifacts.

Journeys live in application manifests#

Application manifests define repositories, targets, required journeys, paths, and ownership. Environment variables provide explicit target coordinates, not hidden application defaults.

Journeys carry stable identity. An onboarding-first-use journey, for example, has an immutable journeyId, a journeyVersion, a UUID journeyVersionId, and a firstSuccessFact; its publication policy names the stable screenId, allowed artifact kinds, minimum evidence level, and whether verified redaction is mandatory.

An explicit PROBIERZ_JOURNEY naming one declared journey runs only that journey. A value declared in journeyOverrides.when.PROBIERZ_JOURNEY instead selects that override's complete group when every condition matches.

Without an explicit journey, the first matching override replaces the default group. Unknown selectors and named groups whose additional conditions do not match are refused; an unrelated matching override cannot make an unknown selector valid.

Discovery is read-only#

Discovery lists surfaces, registered applications, specifications, journey outlines, source identity, and the exact run commands — without installing dependencies, starting a driver, executing a suite, or changing an application repository.

Discovery commands
probierz list             # the surfaces, tools, targets, and env
probierz specs [surface]  # journey specs discovered by the Rust runner
probierz describe <spec>  # static outline of a supported spec file
probierz cmd <target>     # the exact shell command to run a target yourself

Preflight before execution#

`probierz check <target>` is authoritative for toolchain readiness on the current host. It either reports readiness or names the missing prerequisite and its owner. Readiness is not evidence that a journey passed; only a completed run can produce that evidence.

Probierz owns and installs its own tooling through `probierz setup`: npm dependencies and Appium drivers. Host-level prerequisites — the `weles` binary, Xcode, the Android SDK, simulators, physical devices, WinAppDriver, operating-system permissions — are detected and reported with a fix, never installed.

Running a target#

Targets are `web`, `mobile:ios`, `mobile:android`, `desktop:mac`, `desktop:win`, `desktop:cua`, and `tui`. A successful run returns the run result and analysis and writes target-specific artifacts under `test-results/`. Execution may drive a real browser, simulator, device, terminal, or desktop application, so it is not a read-only continuation of discovery.

A selected `--spec` normally comes from the harness registry. It may also be an absolute path to an executable program owned by the application's own repository; Probierz validates that ownership boundary and stamps its report with `owner: "application"`.

First evidence-producing run
probierz check TARGET
probierz run TARGET --app APP_ID --record

Recording and analysis#

  • Web runs keep the screenshots Weles takes at each step and a JSON trace per journey; terminal journeys keep their screens as Markdown or HTML traces.
  • WebdriverIO mobile and desktop-native runs write per-test Appium screen recordings; drivers without screen recording (often Mac2 / WinAppDriver) degrade silently and never fail the run.
  • Recording support is driver-specific and never upgrades a failed run to success.
  • `probierz analyze` parses the canonical Probierz report or a WebdriverIO report, classifies media with sizes, pulls recording metadata via ffprobe, and can extract frame montages via ffmpeg — both optional.
  • Optional recording metadata that cannot be read carries `media[].recordingError` with the ffprobe operation, recording path and actual cause; it is not silently omitted. Explicit frame extraction requires an artifacts directory and refuses failed probing, invalid duration, ffmpeg failure and unreadable frame output instead of returning an empty successful montage. The same refusal reaches CLI/MCP and persisted run evidence used by Desktop failure details. Successful metadata is reused for extraction rather than probing the recording twice.
  • A missing referenced video is also probed: optional analysis keeps its missing flag and actual recordingError, while requested frame extraction refuses that same cause rather than silently skipping the recording. The real media journey removes only its isolated damaged copy to exercise this refusal, then checks recovery against the unchanged original recording.
  • Real media qualification: `node tests/analysis/media.mjs` requires `PROBIERZ`, `PROBIERZ_TEST_SOURCE_REVISION`, `PROBIERZ_TEST_RELEASE_EVIDENCE`, `PROBIERZ_TEST_RECORDED_REPORT` from an actual recorded run, and an explicit `PROBIERZ_TEST_FRAMES` count. It uses real ffprobe/ffmpeg, decodes the extracted frames, then checks optional metadata diagnostics and explicit extraction refusal against a damaged recording copy. Original report and recording hashes must remain unchanged; commands, statuses and source-bound evidence are retained under `probierz-rs/target/real-tests/media`.

Change-driven selection#

`probierz affected` maps a change (git diff against a ref, or explicit files) to the targets it could touch, deterministically and structurally. `probierz ci` composes it: select affected targets, run the ready ones (blocked ones are reported with their fix, not spawned), analyze, and return one verdict with a summary of passed, failed, blocked, and ran.