Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

  1. Scoped Rust formatting.
  2. Locked, explicit-server syndb-ui tests.
  3. Discovery and execution of the canonical test that reproduces both frozen workbench editions and the hosted access contract.
  4. Locked, explicit-web compilation for wasm32-unknown-unknown.
  5. 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 containing server, public, and bundle-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.