Checkout-Based UI Tests
The Just recipes are authoritative for focused UI checks. They call
scripts/ui-tests/run.sh directly, not the full syndb CLI. They use the
existing default Harbor development shell and real Git history. They do not
start Compose, deploy services, alter dependencies, authorize direnv, change
compiler overrides, or weaken the frozen BR-01 payload checks.
Environment
Run from the checkout root in the full development shell (nix develop). The
lean .#dev shell that direnv can load lacks dx, wasm-bindgen, and
chromium:
nix develop -c just ui-preflight
nix develop -c just ui-check
If direnv says .envrc is blocked, stop for operator approval of that exact
checkout. Approval of another worktree is not approval of this one. No recipe
runs direnv allow, falls back to a cached shell, or edits the existing
Python/uv shell hook. A shell-startup failure occurs before these recipes and
must be diagnosed separately.
For the isolated parallel workers, load the approved environment first, source
the coordinator’s worker-env.sh from your own checkout, and set
SYNDB_UI_TEST_BASE_REVISION to the frozen BASE from the handoff. Do not point
output variables at another worker’s directories. Standalone runs default BASE
to HEAD; parallel runs require it explicitly.
ui-preflight audits the full environment. ui-check checks only the tools it
uses, so missing browser executables do not block native/WASM compilation.
Expected Dioxus and wasm-bindgen versions come from Cargo metadata/Cargo.lock.
The selected rustc must have actual wasm32-unknown-unknown core libraries.
Chromium and Chromedriver must share a major version; this is a prerequisite,
not proof of successful session negotiation (owned by the Rust support).
Both nested checkouts must match the recorded HEAD gitlinks and be internally clean. Ordinary dirty application files and linked worktrees are supported. Both frozen manifest revisions must resolve as exact local commits. The recipes never fetch history or reconcile flake/Cargo pins automatically.
Gates
ui-check runs, in order:
- Scoped Rust formatting.
- Locked, explicit-server
syndb-uitests. - Discovery and execution of the canonical test that reproduces both frozen workbench editions and the hosted access contract.
- Locked, explicit-web compilation for
wasm32-unknown-unknown. - Scoped server Clippy, including test targets, with warnings denied.
No command combines server/web using --all-features. Cargo/DX operations are
offline as well as locked: missing dependency materialization is a blocker, not
permission for a recipe to download or rewrite pins. Resolve that separately
under the normal dependency/Canix policy, then rerun.
Browser and Visual Runs
# TARGET is an actual integrated Rust test target supplied by the consumer owner.
nix develop -c just ui-browser TARGET
nix develop -c just ui-visual VISUAL_TARGET
These are separate invocations, not aliases for the real-stack E2E workflow.
The old browser_contract target remains reserved for syndb test e2e and is
not accepted here. The local consumer target must use Agent 4’s support module.
Missing targets/support fail explicitly; the runner does not create stubs.
Each invocation sequentially builds the current fullstack UI into a fresh per-run Cargo/DX
output directory and discovers the emitted server plus adjacent public
there. It does not assume the conventional DX layout. Missing, ambiguous,
non-executable, symlink-containing, or WASM-less bundles fail. A failed build
cannot select an older bundle. This intentionally forgoes cross-run Cargo
artifact reuse for DX output; Harbor’s managed compiler cache remains intact.
The producer copies the verified bundle into a read-only directory, writes its
manifest, discovers the requested Rust tests, then runs them with
--include-ignored --test-threads=1. An empty target fails. Visual mode also
requires a screenshot artifact; the visual target owns matrix completeness.
Capturing PNGs is not visual approval.
Only the frozen inputs are passed from runner to runtime support:
SYNDB_UI_TEST_BUNDLE_DIR: absolute producer-verified directory containingserver,public, andbundle-manifest.json.SYNDB_UI_TEST_RUN_DIR: absolute newly created empty scenario-artifact root.
Agent 4 owns all UI/API/WebDriver processes, browser profiles, strict fixture expectations, cleanup, and runtime compatibility. This runner does not launch any runtime services. Agents 5-6 supply distinct test targets and assertions.
Evidence and Manifest Schema
Every invocation prints its evidence directory. Default location:
target/ui-tests/evidence/MODE.RANDOM; parallel workers use their own
SYNDB_UI_WORKER_STATE/evidence. Logs, bundles and failures are retained.
result.json contains mode, original exit code, error text, source stability,
source identity, tool versions/paths, and stage command/results. Each command
has separate stdout/stderr and combined logs. Source identity includes BASE,
candidate commit, dirty state, a SHA-256 fingerprint of Git/index/worktree and
untracked source contents including nested repositories, Cargo/flake lock
hashes, and recorded/actual nested revisions. Raw source diffs and environment
contents are not written into evidence.
bundle-manifest.json schema version 1:
schema_version: 1
source: {base, revision, fingerprint, dirty, lock_hashes, nested}
tools: {tool_name: {path, version}, ...}
files: [{path: "server" | "public/<relative-path>", sha256}, ...]
build: {stage: "fullstack-build", argv: [...], exit_code: 0}
The manifest itself is not included in files. Agent 4 must revalidate all
listed hashes and reject missing/extra assets before starting the runtime.
Source stability is checked before/after every command and on exit. Detected
change invalidates the evidence and stops subsequent stages (exit 75 if no
earlier command failed). The original nonzero command status is preserved.
Do not edit a checkout while its checks run: boundary fingerprints are not a
filesystem transaction and cannot detect a transient edit restored entirely
between observations. Rebuild after integrating application fixes.
Direct Diagnosis
Within the approved environment, the corresponding commands are:
cargo metadata --locked --offline --no-deps --format-version 1
rustc --print target-libdir --target wasm32-unknown-unknown
cargo fmt -p syndb-ui --check
cargo test --locked --offline -p syndb-ui --no-default-features --features server
cargo test --locked --offline -p syndb-review-workbench --test workbench pinned_editions_and_hosted_contract_reproduce_committed_files -- --exact
cargo build --locked --offline -p syndb-ui --no-default-features --features web --target wasm32-unknown-unknown
cargo clippy --locked --offline -p syndb-ui --no-default-features --features server --all-targets --no-deps -- -D warnings
Never replace missing BR-01 history with HEAD or disable its manifest/byte checks. Report blocked checks separately from failures and passes. Do not declare the UI migration verified from recipe fixtures or compilation alone.
Runner Regression Tests
just ui-runner-test
The Bash fixture suite uses real temporary Git clones/history and explicitly mocked compiler/browser commands. It checks command ordering, version/history failures, missing WASM tooling, exact exit status propagation, source mutation, fresh bundle discovery, stale-input rejection, symlink rejection, nonempty test selection, and visual capture requirements. It does not compile or render the UI and is not a replacement for the gates above. Its artifacts are retained beneath the worker evidence directory.
Ownership and Design Authority
Tartan UI owns shared presentation: ProductShell, Panel, Field,
FeedbackBanner, NavigationList, ThemeToggle, the shared stylesheet, and
the --tartan-* tokens. SynDB owns product behavior: routes, forms, auth/BFF,
theme persistence and document policy, plus the one-way token remap and
intentional .tartan-* selector overrides in
crates/services/ui-dioxus/public/site.css. QueryFabric owns the SyQL editor
component. Tartan upgrades must be checked against both token compatibility and
the local selector overrides.
OpenPencil is a code-derived design reference, not the implementation source.
The Dioxus UI renders first; the importer captures it into .fig artifacts for
review and regression comparison. There is no verified reverse path from edited
.fig files back into code. The accepted reference is the promoted output
described by .openpencil-import/REPORT.md; .openpencil-import.run/ trees
are historical evidence. New contract runs write to
target/openpencil-contracts/ via openpencil/run-contracts.sh. Capture
success and visual approval are separate outcomes: a passing capture means the
import/export/verification gates held, not that a human approved the design.
OpenPencil Tool Contract
All capture paths (direct runners, the aggregate run-contracts.sh, and the
Nautilus candidate capture) resolve the same single tool bundle via
openpencil/resolve-tools.sh: explicit env, else the vendored repo copy in
openpencil/tools/ (byte-identical to skill dioxus-openpencil-import
0.2.0 including the Node shim and license; see PROVENANCE with per-file
hashes; resync deliberately, never drift), else the legacy skill checkout.
Importer, verifier, comparator, and Node shim must stay siblings (verifier
derived from the importer directory — never mix sources). The OpenPencil
executable is selected via OPENPENCIL_COMMAND
(default: the hermetic Nix openpencil package in the devshell, falling back
to npx --yes @open-pencil/cli@0.14.0 outside it) and shared by capture,
preparation, and verification; the artifact
gate checks executable identity plus the recorded detectedVersion and
capability booleans in provenance/openpencil-capabilities.json against
openpencil/profiles.toml, not the npm command spelling. The importer and
verifier run in their pinned PEP 723 environments (playwright==1.61.0,
Pillow==12.3.0); synthetic browser tests provision the same Playwright via
uv run --with. Missing tools fail before any build or service starts.