Skip to content

Latest commit

 

History

History
185 lines (148 loc) · 9.7 KB

README.md

File metadata and controls

185 lines (148 loc) · 9.7 KB

ui/tests — Muster UI acceptance harness (P4)

muster-ui-test.mjs drives muster-ui inside a logos-basecamp host via logos-qt-mcp, headless (offscreen), and asserts the real lifecycle surfaces:

  1. render — the view instantiates in the ui-host (the exo-c6a blocker; ADR-013),
  2. health — muster_module.health() marshals back to "ok",
  3. propose — the module re-derives the EIP-712 safeTxHash and the re-materialization strip shows it (F-4 / invariant 1 — the real check, not the prototype's simulated hashes).
  4. lifecycle — collecting owner signatures advances the intent proposed → collecting → executable. Each signature is verified by the module (recovers to a configured owner) before it counts toward the threshold. The test pastes two pre-signed anvil-owner signatures over the intent's safeTxHash; regenerate them (see the OWNER_SIGS comment in the test) if the effect or Safe config changes.
  5. reject + reset — a signature that does not recover to a configured owner is refused (the module returns "rejected", the intent does not advance), the error banner shows the reason, and reset clears the intent for a fresh walkthrough. Off-chain; no anvil needed.
  6. submit — an executable intent is sent on-chain: the module assembles the Safe execTransaction from the collected signatures, submits it through the user's RPC, and reads finality from the receipt (submitted → final). No indexer, no Safe service. Requires anvil (see below); it is the only test that moves the Safe on-chain, so its effect nonce (0) must match a fresh Safe.
  7. walkthrough — toggling the walkthrough renders the ADR-012 claims registry (the six lifecycle steps with their PROTECTS / GAP badges), asserting the generated ClaimsRegistry.qml cards are present. Off-chain; no anvil needed.
  8. room render — clicking the Room nav switches surfaces (the room becomes visible, home hides) and the room draws its join affordance (topic field + Join). This is the on-display gate for Room.qml + MusterCard.qml (ADR-011: nix build does not evaluate QML, so a bad type name would blank the view). It stops at render on purpose — joining drives coordinate_join → DeliveryTransport, which needs delivery_module (muster_module declares no dependency on it and this bake does not carry it), so the functional propose → card → contribute loop belongs with the live delivery node (the documented cross-host item). The fold those cards render from is covered headless (module/tests/coordination_surface_test.nim step 6). Off-chain.

It writes screenshots to $MUSTER_SHOT (default ./muster-ui.png), with -executable / -final / -room suffixes for the respective surfaces.

Status: tests 1–5, 7, 8 run in the offscreen bake (submit additionally needs anvil). The lifecycle five were 6/6 green as of 2026-08-21 (ADR-013 + exo-4a5

  • exo-27b0 + exo-308); the room render test was added 2026-08-24 and awaits a harness run against the bake (the local basecamp bake-in is the standing blocker). See docs/02-implementation-plan.md ADR-013 and pebble exo-193 for the full story.

anvil (for the submit test)

The module submits through http://127.0.0.1:8545 against a Safe at its configured address. Bring that up before running the full harness:

# a fresh anvil + the real Safe v1.4.1 (Safe nonce 0), deterministically at
# 0xEb4520E32862D2adFa2aF042f0B5eA2041dEE841, owners = anvil accounts 0/1/2, 2-of-3:
infra/anvil/devnet.sh

Without anvil the first four tests still pass; the submit test fails with the backend's "is the RPC reachable?" message. Run only the off-chain tests with a filter, e.g. node ui/tests/muster-ui-test.mjs --ci <app> health.

Why basecamp (not the standalone runner)

logos-standalone-app renders no ui_qml view on the current stack; logos-basecamp is the working host. Per ADR-013, muster-ui must be built on a basecamp-coherent logos-module-builder (its ui/flake.nix pins basecamp's builder rev) so the generated muster_module client + QtRO view-glue ABI-match basecamp's ui-host.

Producing the app-under-test

The harness takes any basecamp binary that has muster_module + muster_ui baked in. Today that means a local logos-basecamp dev build (the bake-in edits are not committed to the upstream basecamp repo). Two supporting fixes are required until they land upstream (both tracked in ADR-013 / exo-193):

  • Builder RUNPATH fix (logos-module-builder): the Nim codegen.nim.link libs (secp256k1) need their lib dir in the plugin RUNPATH. Fixes non-bundled hosts.
  • basecamp co-location: basecamp's app.nix strips external module RUNPATH entries and logos-core unsets LD_LIBRARY_PATH, so libsecp256k1.so.5 must be co-located in the module dir ($ORIGIN).

1. Bake muster into a local logos-basecamp checkout

In logos-basecamp/flake.nix, add the two inputs:

muster_module.url = "git+file:///ABS/PATH/TO/muster?dir=module";
muster_ui.url     = "git+file:///ABS/PATH/TO/muster?dir=ui";

Use git+file: (the git-TRACKED tree), not path:. A path: input copies the working directory including untracked build symlinks and scratch (result, *.log), which changes the muster_module derivation from what cd module && nix build produces — and that rebuild fails the Nim compile with secp256k1.nim: cannot open file: pkg/results. git+file: copies only tracked files, so it matches the standalone build (which builds clean). Commit your muster changes first — git+file: won't see uncommitted view edits.

add them to the outputs = { ... } argument set, bind their installs in the forAllSystems let (co-locating secp for the basecamp case):

musterUiInstall     = muster_ui.packages.${system}.install;
musterModuleInstall = (import nixpkgs { inherit system; }).runCommand "muster-module-install-secp" {} ''
  cp -r --no-preserve=mode ${muster_module.packages.${system}.install} $out
  cp -L ${(import nixpkgs { inherit system; }).secp256k1}/lib/libsecp256k1.so.5 $out/modules/muster_module/
'';

add musterModuleInstall, musterUiInstall to the packages = forAllSystems ({ … }) argument set, and append them to the dev app's module set:

musterInstalls = [ musterModuleInstall musterUiInstall ];
# …
app = import ./nix/app.nix { …; installedModules = installedDev ++ musterInstalls; };

Bake in muster's own .install outputs (as above), not installDev over .lib — basecamp's installDev re-bundle of .lib fails with qml/Main.qml not found (a bundler-version skew); the standalone install is self-consistent.

The release AppImage no longer comes from this bake-in (since 0.3.0): scripts/release-appimage.sh installs Muster into Basecamp's own released AppImage, no checkout needed (../RELEASING.md). The distributed-app bake-in below is kept for a dev build of Basecamp that needs Muster inside — appDistributed uses portable-keyed modules, so use the install-portable outputs, and append them there too:

musterUiInstallPortable     = muster_ui.packages.${system}.install-portable;
musterModuleInstallPortable = (import nixpkgs { inherit system; }).runCommand "muster-module-install-portable-secp" {} ''
  cp -r --no-preserve=mode ${muster_module.packages.${system}.install-portable} $out
  cp -L ${(import nixpkgs { inherit system; }).secp256k1}/lib/libsecp256k1.so.5 $out/modules/muster_module/
'';
# …
appDistributed = import ./nix/app.nix { …; installedModules = installedDistributed ++ [ musterModuleInstallPortable musterUiInstallPortable ]; };

Then nix build <basecamp>#bin-appimage (or make appimage) yields result-appimage/logos-basecamp.AppImage with muster inside.

2. Build everything

LOGOS_CACHE="--extra-substituters https://cache.nix.logos.co/public \
  --extra-trusted-public-keys public:l4HrXgL4nw246+LBh2SOJyhz64BoGegOYLheT/iIAPU= \
  --accept-flake-config"

# the app-under-test (muster baked in) and the qt-mcp framework
nix build /PATH/TO/logos-basecamp#app          --out-link result-app  $LOGOS_CACHE
nix build /PATH/TO/logos-basecamp#logos-qt-mcp --out-link result-mcp  $LOGOS_CACHE

3. Run the harness

LOGOS_QT_MCP="$PWD/result-mcp" \
MUSTER_SHOT="$PWD/muster-ui.png" \
  node ui/tests/muster-ui-test.mjs --ci "$PWD/result-app/bin/LogosBasecamp"

Expected: 3 passed, 0 failed, and muster-ui.png showing the Muster view — the Safe account from describe(), the proposed intent, the green re-materialization strip with the re-derived safeTxHash, and module.health() → ok.

Which UI build it tests (exo-607)

The harness drives whatever app binary you pass it, so the build is chosen at bake time: step 1 bakes in either muster_ui's C++ backend or, once it exists, the Nim (seaqt) one. How the Nim build reaches this harness depends on exo-607's hosting decision (docs/design/seaqt-ui.md §6):

  • Option A, a Nim plugin inside Basecamp: bake it the same way and pass the same binary. The harness is unchanged.
  • Option B, a standalone seaqt app: there is no Basecamp sidebar to click, so openMuster would need a standalone path.

The offscreen self-tests select their build with MUSTER_UI=cpp|nim instead (scripts/lib/ui-build.sh, scripts/ui-parity.sh).

Extending

Add a test("muster_ui: …", async (app) => { … }) block. Useful primitives on app: click(text), expectTexts([…]) (exact match), waitFor(fn, opts), screenshot(), and inspector.send("findByProperty" | "setProperty" | "callMethod" | "evaluate", …). Find controls by objectName (the composer fields are proposeTo / proposeValue / proposeNonce / proposeButton).