Back to Details

hud-manual-testing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Claude HUD Manual Testing

Claude HUD 手动测试

Verify core functionality works after code changes. Uses the project's reset script and debugging tools.
验证代码变更后核心功能是否正常运行。使用项目的重置脚本和调试工具。

When to Use

适用场景

  • After implementing significant features
  • After fixing state detection bugs
  • Before commits affecting session tracking
  • When user asks to "test the app" or "verify it works"
  • 完成重要功能开发后
  • 修复状态检测Bug后
  • 提交影响会话跟踪的代码前
  • 用户要求“测试应用”或“验证应用可正常运行”时

Testing Workflow

测试工作流

1. Full Reset

1. 完全重置

Reset to clean state to test first-run experience and verify nothing depends on stale data:
bash
./scripts/dev/reset-for-testing.sh
This clears:
  • App UserDefaults (layout, setup state)
  • ~/.capacitor/
    (sessions, locks, activity)
  • Hook script and registrations
  • Rebuilds app and launches it
重置至干净状态，以测试首次运行体验并验证没有功能依赖于过期数据：
bash
./scripts/dev/reset-for-testing.sh
该脚本会清除：
  • 应用UserDefaults（布局、设置状态）
  • ~/.capacitor/
    （会话、锁、活动记录）
  • Hook脚本及注册信息
  • 重新构建并启动应用

2. First-Run Verification

2. 首次运行验证

After reset, verify the onboarding flow:
  1. Setup screen appears - App should detect missing hooks
  2. Hook installation works - Click install, verify success
  3. Empty project list - No projects pinned yet
重置完成后，验证引导流程：
  1. 显示设置界面 - 应用应检测到缺失的hooks
  2. Hook安装正常 - 点击安装，验证安装成功
  3. 项目列表为空 - 尚未固定任何项目

3. Core Functionality Checklist

3. 核心功能检查清单

Test each feature manually:
FeatureHow to TestExpected
Add projectClick +, select a project folderProject appears in list
Session detectionStart Claude in that projectState shows Ready/Working
State transitionsType prompt, wait for responseWorking → Ready transitions
Lock detectionCheck 
ls ~/.capacitor/sessions/
Lock dir exists while Claude runs
Session endExit Claude sessionState returns to Idle
手动测试各项功能：
功能测试方法预期结果
添加项目点击+，选择项目文件夹项目出现在列表中
会话检测在该项目中启动Claude状态显示为就绪/工作中
状态转换输入提示词，等待响应工作中 → 就绪 状态正常转换
锁检测执行 
ls ~/.capacitor/sessions/
Claude运行时锁目录存在
会话结束退出Claude会话状态返回至空闲

4. Debug Commands

4. 调试命令

If issues occur, check these:
bash
undefined
若出现问题，执行以下命令排查：
bash
undefined

Watch hook events in real-time

实时监控Hook事件

tail -f ~/.capacitor/hud-hook-debug.log
tail -f ~/.capacitor/hud-hook-debug.log

View current session states

查看当前会话状态

cat ~/.capacitor/sessions.json | jq .
cat ~/.capacitor/sessions.json | jq .

Check active locks

检查活动锁

ls -la ~/.capacitor/sessions/
ls -la ~/.capacitor/sessions/

Check for process

检查进程

ps aux | grep -E "(claude|hud-hook)"
undefined
ps aux | grep -E "(claude|hud-hook)"
undefined

5. Quick Restart (No Reset)

5. 快速重启（不重置）

For iterative testing without full reset:
bash
./scripts/dev/restart-app.sh
This rebuilds Rust + Swift and restarts the app, keeping state intact.
用于无需完全重置的迭代测试：
bash
./scripts/dev/restart-app.sh
该脚本会重新构建Rust + Swift并重启应用，保留现有状态。

Common Issues

常见问题

State stuck on Working/Waiting

状态卡在工作中/等待中

Check if lock holder is alive:
bash
cat ~/.capacitor/sessions/*.lock/pid | xargs -I {} ps -p {}
If PID is dead but lock exists, the cleanup should remove it on next app launch.
检查锁持有进程是否存活：
bash
cat ~/.capacitor/sessions/*.lock/pid | xargs -I {} ps -p {}
若PID已终止但锁仍存在，下次应用启动时清理流程应自动移除该锁。

Hook events not firing

Hook事件未触发

Verify hooks are registered:
bash
cat ~/.claude/settings.json | jq '.hooks'
Should show entries for SessionStart, UserPromptSubmit, etc. pointing to 
hud-state-tracker.sh
.
验证hooks已注册：
bash
cat ~/.claude/settings.json | jq '.hooks'
应显示指向
hud-state-tracker.sh
的SessionStart、UserPromptSubmit等条目。

UniFFI checksum mismatch

UniFFI校验和不匹配

Regenerate bindings:
bash
cargo build -p hud-core --release
cd core/hud-core && cargo run --bin uniffi-bindgen generate --library ../../target/release/libhud_core.dylib --language swift --out-dir ../../apps/swift/bindings/
cp ../../apps/swift/bindings/hud_core.swift ../../apps/swift/Sources/ClaudeHUD/Bridge/
rm -rf ../../apps/swift/.build
重新生成绑定：
bash
cargo build -p hud-core --release
cd core/hud-core && cargo run --bin uniffi-bindgen generate --library ../../target/release/libhud_core.dylib --language swift --out-dir ../../apps/swift/bindings/
cp ../../apps/swift/bindings/hud_core.swift ../../apps/swift/Sources/ClaudeHUD/Bridge/
rm -rf ../../apps/swift/.build

Verification Summary

验证总结

After testing, confirm:
  • App launches without crash
  • Hooks install successfully on first run
  • Projects can be added/removed
  • Session states reflect actual Claude activity
  • States transition correctly (Idle → Ready → Working → Ready → Idle)
  • No orphaned lock holders accumulate
测试完成后，确认以下项：
  • 应用启动无崩溃
  • Hooks在首次运行时安装成功
  • 项目可正常添加/移除
  • 会话状态准确反映Claude的活动情况
  • 状态转换正常（空闲 → 就绪 → 工作中 → 就绪 → 空闲）
  • 无孤立锁持有者堆积