129 lines
5.1 KiB
Markdown
129 lines
5.1 KiB
Markdown
# 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`
|
||
- release binary 复验：`CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse cargo build --release -p dbtool-tui`
|
||
- 无 Rust 工具链环境：直接使用 `./target/debug/dbtool-tui`
|
||
- 若当前 runner 的 `CARGO_REGISTRIES_CRATES_IO_PROTOCOL` 为空字符串，裸 `cargo` 会直接失败；请按上面的显式 override 执行。
|
||
|
||
## 最小入口
|
||
|
||
正常终端尺寸：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
release binary 同口径：
|
||
|
||
```bash
|
||
scripts/tui/smoke-tty.sh ./target/release/dbtool-tui 40 120 /tmp/cmp60-dbtool-tui-release-smoke.log
|
||
grep -aq "Workspace" /tmp/cmp60-dbtool-tui-release-smoke.log
|
||
grep -aq "Loading" /tmp/cmp60-dbtool-tui-release-smoke.log
|
||
```
|
||
|
||
小终端降级：
|
||
|
||
```bash
|
||
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 数据。
|
||
- 当前推荐的单命令复验入口：
|
||
|
||
```bash
|
||
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 profile 的 activate / inspect / query / export，不覆盖连接新增 / 编辑 / 删除 / 保存或 secret session cache。
|
||
- 若 GUI host 或宿主机必须把 demo host 改到 `127.0.0.1`，请在启动前设置 `DBTOOL_TUI_POSTGRES_HOST` / `DBTOOL_TUI_POSTGRES_PORT` 与 `DBTOOL_TUI_MYSQL_HOST` / `DBTOOL_TUI_MYSQL_PORT`；这是 operator fallback，不得记成连接管理 happy path。
|
||
|
||
- 若只想准备 demo stack 与 seed 数据：
|
||
|
||
```bash
|
||
scripts/tui/demo-stack.sh up
|
||
scripts/tui/demo-stack.sh seed
|
||
scripts/tui/demo-stack.sh status
|
||
```
|
||
|
||
## Connection management smoke
|
||
|
||
若要复核新的 in-app 连接管理路径，建议先隔离 profile store：
|
||
|
||
```bash
|
||
export DBTOOL_TUI_PROFILE_STORE=/tmp/dbtool-tui-profiles.json
|
||
rm -f "$DBTOOL_TUI_PROFILE_STORE"
|
||
cargo run -p dbtool-tui
|
||
```
|
||
|
||
进入 TUI 后按下面的手工路径复核：
|
||
|
||
1. 按 `2` 进入 `Connections`
|
||
2. 按 `n` 新建 profile
|
||
3. 在中间 `Query Editor` 中用 `i` 编辑字段，`Enter` 提交字段
|
||
4. 按 `t` 做 staged connect + inspect 测试
|
||
5. 按 `s` 保存并激活 profile
|
||
6. 确认左侧列表、右侧 `Inspector` 和 `Status & Activity` 同步切到新活动连接
|
||
7. 按 `e` 编辑已保存 profile，确认修改可再次测试并保存
|
||
8. 按 `d` 删除 profile，确认 `Enter` 才执行删除，`Esc` 可取消
|
||
|
||
记录时至少包含：
|
||
|
||
- `DBTOOL_TUI_PROFILE_STORE` 的实际路径
|
||
- 新建 profile 的 driver 类型（SQLite / PostgreSQL / MySQL）
|
||
- `t` 的结果文案
|
||
- `s` 后的激活结果与当前连接名称
|
||
- 删除确认路径是否被 `Enter` / `Esc` 正确区分
|
||
|
||
## 非 TTY 预期行为
|
||
|
||
```bash
|
||
./target/release/dbtool-tui --help
|
||
```
|
||
|
||
2026-03-31 当前 release binary 实测行为：
|
||
|
||
- 退出码：`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、导出路径和日志路径。
|
||
- 若使用 host override，额外记录具体环境变量；不得把这条路径写成普通用户主流程。
|
||
- 若源码不可重建，要明确记为环境 blocker，不得伪造成产品失败。
|
||
|
||
## CI 约束
|
||
|
||
- 当前仓库还没有正式接入 `dbtool-tui` 的 GitHub Actions smoke。
|
||
- 当前仓库也还没有 `dbtool-tui` 的 packaged-artifact workflow / package script；`target/release/dbtool-tui` 只能记为 release-binary 级别证据，不能上抬成已验证的 distributable artifact。
|
||
- 后续 CI 若补齐，应直接复用 `scripts/tui/smoke-tty.sh`，不要重新发明另一套启动口径。
|