E2E scripts catalog

FrankenTUI’s top-level E2E layer is a set of shell and Python scripts in scripts/. Each one drives a real ftui-demo-showcase (or a harness) through a PTY and captures structured evidence. CI runs a subset; humans run them for local regression hunting.

Source: /scripts/ at the repo root (27 scripts).

Core E2E

scripts/e2e_test.sh

Main PTY suite runner. Wraps tests/e2e/scripts/run_all.sh and orchestrates budget, span, tile, and selector scenarios. JSONL run_end events are validated against tests/e2e/lib/e2e_jsonl_schema.json.

./scripts/e2e_test.sh                 # Full run
./scripts/e2e_test.sh --quick         # Inline + cleanup only
./scripts/e2e_test.sh --no-large --no-budget --verbose

Artifacts land under /tmp/ftui_e2e_<timestamp>/: 00_environment.log, e2e.log, results/*.json, results/summary.json, raw *.pty captures.

Flags: --verbose, --quick, --no-large, --no-budget, --no-span, --no-tile, --no-selector, --trace-only.

scripts/widget_api_e2e.sh

Comprehensive widget API verification — creation, rendering, state, event handling — with detailed logging for every failure.

./scripts/widget_api_e2e.sh

scripts/demo_showcase_e2e.sh

Demo showcase end-to-end: screen navigation, interaction patterns, determinism checks across the 46 screens. Sets E2E_DETERMINISTIC=1 E2E_SEED=0 E2E_TIME_STEP_MS=100 by default.

./scripts/demo_showcase_e2e.sh

Emits VFX and layout-inspector JSONL with schema v1 fields.

scripts/pane_e2e.sh

Pane layout + splitting + resizing + input routing.

./scripts/pane_e2e.sh

scripts/cross_platform_e2e.sh

Cross-platform rendering validation across multiple terminal capability profiles.

./scripts/cross_platform_e2e.sh

scripts/vt_support_matrix_e2e.sh

Terminal emulator compatibility smoke test across the VT feature matrix.

./scripts/vt_support_matrix_e2e.sh

Doctor / certification

scripts/doctor_frankentui_happy_e2e.sh

Happy-path certification for doctor_frankentui. Drives a full replay through the CLI and writes the standard happy-path manifest.

./scripts/doctor_frankentui_happy_e2e.sh                          # Auto-timestamped dir
./scripts/doctor_frankentui_happy_e2e.sh /tmp/custom_run_root     # Explicit

Artifacts under /tmp/doctor_frankentui/e2e/happy_<timestamp>/:

• meta/step_results.tsv
• meta/summary.json, meta/summary.txt
• meta/events.jsonl, meta/events_validation_report.json
• meta/command_manifest.txt
• meta/env_snapshot.txt
• meta/tool_versions.txt
• meta/artifact_manifest.json

See artifacts contract.

scripts/doctor_frankentui_failure_e2e.sh

Failure-path certification. Runs adversarial cases that exercise the error-handling paths and leaves triage material behind.

./scripts/doctor_frankentui_failure_e2e.sh

Artifacts under /tmp/doctor_frankentui/e2e/failure_<timestamp>/:

• cases/<case_id>/… per-case captures
• meta/case_results.json, meta/case_results.tsv
• meta/summary.json, meta/summary.txt
• meta/events.jsonl, meta/events_validation_report.json
• meta/command_manifest.txt, meta/env_snapshot.txt, meta/tool_versions.txt

Post-process with replay triage.

scripts/doctor_frankentui_determinism_soak.sh

Runs N iterations of happy and failure flows, then compares frame checksums across iterations. Non-volatile divergence fails the gate.

./scripts/doctor_frankentui_determinism_soak.sh                             # 3 iters
DOCTOR_FRANKENTUI_SOAK_RUNS=10 ./scripts/doctor_frankentui_determinism_soak.sh

Artifacts under /tmp/doctor_frankentui/determinism_soak_<timestamp>/:

• meta/run_index.tsv
• meta/determinism_report.json
• meta/determinism_report.txt

Full guide: determinism soak.

scripts/doctor_frankentui_coverage.sh

Enforces the coverage gate for the doctor_frankentui crate. Runs cargo llvm-cov --branch --summary-only --json and compares against crates/doctor_frankentui/coverage/thresholds.toml.

./scripts/doctor_frankentui_coverage.sh
./scripts/doctor_frankentui_coverage.sh /tmp/doctor_frankentui_coverage_gate

Artifacts under target/doctor_frankentui_coverage/ (default):

• coverage_summary.json
• coverage_gate_report.json
• coverage_gate_report.txt

Requires python3 (3.11+ or tomli installed), cargo, and cargo-llvm-cov. Full guide: coverage gate.

scripts/doctor_frankentui_shadow_compare.sh

Shadow-run comparison driven through the doctor_frankentui capture pipeline. Validates baseline vs candidate frame parity for a named scenario (default all).

./scripts/doctor_frankentui_shadow_compare.sh
./scripts/doctor_frankentui_shadow_compare.sh /tmp/shadow_out resize_storm

Artifacts under /tmp/doctor_frankentui/shadow_compare_<timestamp>/:

• artifacts/shadow_report.json
• artifacts/replay.sh
• meta/run_index.tsv
• meta/summary.json, meta/summary.txt
• meta/artifact_manifest.json
• meta/command_manifest.txt

scripts/runtime_shadow_compare.sh

Lower-level shadow-run for ftui-runtime changes only — skips the full doctor_frankentui scaffolding and drives the tests directly.

./scripts/runtime_shadow_compare.sh
./scripts/runtime_shadow_compare.sh /tmp/rt_shadow tick_counter

Artifacts under /tmp/ftui_runtime_shadow_compare/<timestamp>/: artifacts/shadow_report.json, artifacts/replay.sh, meta/….

scripts/doctor_frankentui_replay_triage.py

Post-mortem analyser for failure runs. Extracts the top-N failure signals from meta/events.jsonl, enriches them with event classification, and prints a compact triage summary (or emits JSON).

python3 ./scripts/doctor_frankentui_replay_triage.py \
    --run-root /tmp/doctor_frankentui/e2e/failure_20260423T000000Z \
    --max-signals 8

Optional: --output-json <path>, --max-timeline 40. See replay triage for signal semantics.

scripts/doctor_frankentui_validate_jsonl.py

Schema validator for events.jsonl. Used by the happy/failure scripts as part of meta/events_validation_report.json.

python3 ./scripts/doctor_frankentui_validate_jsonl.py /path/to/events.jsonl

scripts/doctor_frankentui_no_fake_gate.py

Static gate: scans the codebase for forbidden mock/fake patterns that would violate the no-mock policy .

python3 ./scripts/doctor_frankentui_no_fake_gate.py

Performance gates

scripts/perf_regression_gate.sh

Compares criterion benchmark results against tests/baseline.json p99 budgets. Exits non-zero if any observed mean exceeds the baseline by more than threshold_pct.

./scripts/perf_regression_gate.sh              # Run benches + check
./scripts/perf_regression_gate.sh --check-only # Parse existing results
./scripts/perf_regression_gate.sh --quick      # CI-friendly sampling
./scripts/perf_regression_gate.sh --json       # Emit JSONL report
./scripts/perf_regression_gate.sh --flamegraph # Generate flamegraphs
./scripts/perf_regression_gate.sh --update     # Refresh baseline

Artifacts under target/regression-gate/: regression_report.jsonl, flamegraphs (when --flamegraph).

Full guide: benchmark gate.

scripts/bench_budget.sh

Budget-constrained benchmarking. Validates that documented performance budgets are still met; exit 0 on success.

./scripts/bench_budget.sh
./scripts/bench_budget.sh --quick
./scripts/bench_budget.sh --check-only
./scripts/bench_budget.sh --json

Demo + visual FX

scripts/demo_showcase_screen_sweep_e2e.sh

Iterates all 46 demo screens via FTUI_HARNESS_VIEW=<id> and captures one PTY snapshot per screen.

./scripts/demo_showcase_screen_sweep_e2e.sh

scripts/demo_text_effects_e2e.sh

Text-effects validation — styling, animation, flicker avoidance.

./scripts/demo_text_effects_e2e.sh

scripts/demo_visual_fx_e2e.sh

VFX harness. Deterministic frame output for doom, quake, plasma, and the other registered effects. Reads --vfx-* flags from the demo CLI.

./scripts/demo_visual_fx_e2e.sh

scripts/e2e_demo_tour.sh

Guided-tour E2E. Auto-plays the tour across key screens and validates the generated report.

./scripts/e2e_demo_tour.sh

scripts/perf_hud_demo.sh

Launches the demo showcase on the Performance screen with convenient knobs. Useful for manual HUD verification — not a CI gate.

./scripts/perf_hud_demo.sh
./scripts/perf_hud_demo.sh --inline --ui-height 12
./scripts/perf_hud_demo.sh --pty --auto-exit 1500

Flags: --inline, --ui-height N, --auto-exit MS, --pty, --no-mouse. See performance HUD.

scripts/perf_hud_e2e.sh

HUD-driven performance + degradation-tier validation.

./scripts/perf_hud_e2e.sh

scripts/pane_profile.sh

Pane profiling runner — performance analysis of pane operations.

./scripts/pane_profile.sh

Specialised validations

scripts/hover_stabilizer_e2e.sh

Hover-jitter stabilisation check. Validates the CUSUM-backed hover stabiliser; links to CUSUM.

./scripts/hover_stabilizer_e2e.sh

scripts/command_palette_e2e.sh

PTY test for the keyboard-driven command palette. Validates the Bayesian evidence ledger end-to-end.

./scripts/command_palette_e2e.sh

scripts/a11y_transitions_e2e.sh

Accessibility mode transitions — screen reader mode, high contrast, keyboard-only navigation.

./scripts/a11y_transitions_e2e.sh

scripts/test_double_buffer.sh

Validates the O(1) double-buffer swap in the render kernel.

./scripts/test_double_buffer.sh

Fuzzing and stress

scripts/fuzz_campaign_e2e.sh

cargo-fuzz campaign across all registered targets. Fails on crashes, reports coverage, and honours pre-existing crash artifacts.

./scripts/fuzz_campaign_e2e.sh
FUZZ_DURATION_SECS=3600 ./scripts/fuzz_campaign_e2e.sh   # 1-hour CI run

Env: FUZZ_DURATION_SECS, FUZZ_MAX_LEN, FUZZ_JOBS, LOG_DIR, NIGHTLY_TOOLCHAIN.

Utilities

scripts/pull_latest_reference_library_repos.sh

Pulls the latest external reference implementations used by the cross-library comparison tests. Not part of a CI gate — a maintainer utility.

./scripts/pull_latest_reference_library_repos.sh

Environment summary

Scripts honour the determinism fixtures:

• E2E_DETERMINISTIC, E2E_SEED, E2E_TIME_STEP_MS
• FTUI_DEMO_DETERMINISTIC, FTUI_DEMO_SEED
• FTUI_TEST_PROFILE, FTUI_TEST_PROFILE_COMPARE
• FTUI_HARNESS_VIEW (selects demo screen)
• FTUI_PERF_HUD_JSONL (enables perf HUD JSONL)

Full list: env vars reference.

Related