paperclip/dbtool-cli-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a28dab4cd9f7a21dd0d537f65335bea71ea567fd
dbtool-cli-v1/TUI_SMOKE_RUNBOOK.md
Paperclip CTO a28dab4cd9
Some checks failed
release-smoke / macos-13 / x86_64-apple-darwin (push) Has been cancelled
Details
release-smoke / ubuntu-latest / x86_64-unknown-linux-gnu (push) Has been cancelled
Details
release-smoke / windows-latest / x86_64-pc-windows-msvc (push) Has been cancelled
Details
feat(usable): package gui-host validation snapshot 
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-03-31 10:21:36 +00:00

3.0 KiB
Raw Blame History

dbtool-tui TTY Smoke Runbook

Contract

  • dbtool-tui 是交互式 TUI；启动验证必须提供真实 TTY。
  • 当前最小可重复入口是 scripts/tui/smoke-tty.sh <binary-path>。
  • dbtool-tui --help、dbtool-tui --version 不是有效的 TUI smoke 替代路径。
  • 非 TTY 启动当前应退出 1，并输出明确的 TTY-required 提示。

前置条件

  • Linux runner，且可用 script（util-linux）。
  • 已有可执行二进制：
    • 源码环境：CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse cargo build -p dbtool-tui
    • 无 Rust 工具链环境：直接使用 ./target/debug/dbtool-tui
  • 若当前 runner 的 CARGO_REGISTRIES_CRATES_IO_PROTOCOL 为空字符串，裸 cargo 会直接失败；请按上面的显式 override 执行。

最小入口

正常终端尺寸：

scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui
grep -aq "Workspace" /tmp/dbtool-tui-smoke.log
grep -aq "Loading" /tmp/dbtool-tui-smoke.log

小终端降级：

scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui 20 90 /tmp/dbtool-tui-small.log
grep -aq "Terminal Too Small" /tmp/dbtool-tui-small.log
grep -aq "Resize the terminal" /tmp/dbtool-tui-small.log

PostgreSQL / MySQL live path

  • 当前 runner 的可达 network path 是 host.docker.internal:55432（PostgreSQL）与 host.docker.internal:53306（MySQL），不是 127.0.0.1。
  • 当前 runner 即使缺少 docker compose 子命令，也可通过 scripts/tui/demo-stack.sh 与 bootstrap fallback 建立同一套 demo 数据。
  • 当前推荐的单命令复验入口：
export DBTOOL_PASSWORD=dbtool
scripts/tui/live-network-smoke.sh postgres ./target/debug/dbtool-tui
scripts/tui/live-network-smoke.sh mysql ./target/debug/dbtool-tui
  • 若只想准备 demo stack 与 seed 数据：
scripts/tui/demo-stack.sh up
scripts/tui/demo-stack.sh seed
scripts/tui/demo-stack.sh status

非 TTY 预期行为

./target/debug/dbtool-tui --help

2026-03-28 当前源码重建后二进制实测行为：

  • 退出码：1
  • stderr：
    • dbtool-tui requires an interactive TTY on stdin and stdout.
    • Detected stdin TTY: false
    • Detected stdout TTY: false
    • Use \scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui` for repeatable smoke validation.`
    • `--help` is not a supported TUI smoke path.

这条路径的意义是确认“限制被清楚记录”，不是把 --help 视为 smoke 成功。

QA 记录要求

  • 记录二进制路径、命令、终端尺寸、退出码、日志路径。
  • 正常尺寸至少确认日志里出现 Workspace、Loading。
  • 小终端路径至少确认日志里出现 Terminal Too Small、Resize the terminal。
  • network live 路径至少记录目标数据库、endpoint、导出路径和日志路径。
  • 若源码不可重建，要明确记为环境 blocker，不得伪造成产品失败。

CI 约束

  • 当前仓库还没有正式接入 dbtool-tui 的 GitHub Actions smoke。
  • 后续 CI 若补齐，应直接复用 scripts/tui/smoke-tty.sh，不要重新发明另一套启动口径。