用途：仅面向 Warp GUI 桌面前端（app/ crate，WarpUI 像素/GPU 框架），用于在 crates/integration/ 下的自定义框架中编写、运行和调试 Rust 集成测试。不适用于无头 TUI（crates/warp_tui 等），TUI 请改用 tui-ui-guidelines、tui-testing、tui-verify-change。
何时使用：集成测试会启动真实 Warp 实例、隔离测试主目录、注入合成 UI 与终端事件，并轮询断言直至成功或超时，属于仓库中开销最大、最易不稳定的测试。适合覆盖跨组件风险，如真实终端/PTY 与 shell 集成（bash、zsh、fish）、设置/键位/偏好端到端生效、跨组件流程（命令面板到编辑器到终端、焦点与面板管理、标签页/窗口生命周期）、仅在真实运行时可复现的输入与渲染路径，以及用户可见回归。确定性、可在进程内触达的逻辑应写单元测试；仅需 TUI 渲染应使用 tui-testing；仅需截图或人工查看应使用 computer_use 或 gui-integration-test-video。
框架要点：crates/integration/src/bin/integration.rs 为手动测试运行器，注册名称到 Builder 工厂，每次运行一个命名测试；crates/integration/tests/common/mod.rs 为 cargo test/nextest 使用的外层外壳，转发受限环境变量，并在特殊重跑码时最多重跑 10 次；crates/integration/src/test.rs 为模块入口；ui_tests.rs 与 shell_integration_tests.rs 为测试清单；builder.rs 设置默认超时、隔离 HOME、shell rc 文件、用户偏好与真实显示模式；warpui_core 的 driver.rs 与 step.rs 负责执行步骤、重试、前置条件重跑、截图、录屏与工件导出；app/src/integration_testing/ 提供高层辅助与断言。
新增测试步骤：在 crates/integration/src/test/ 下实现 pub fn test_name() -> Builder；在 test.rs 中注册模块并 pub use 导出；在 bin/integration.rs 添加 register_test!(test_name);；并把测试加入 ui_tests.rs 或 shell_integration_tests.rs 之一。仅放在 src/test/*.rs 不足以被 nextest 运行。默认应可在 CI 运行，仅在明确需要手动覆盖或确有不可稳定在 CI 运行的原因时才加 #[ignore]。
常用写法与运行：测试体倾向使用少量聚焦步骤并命名，优先使用 app/src/integration_testing/ 辅助函数，命名断言优于匿名断言，使用轮询断言而非 sleep，跨步骤传值用 StepDataMap；真正环境性问题才用 PreconditionFailed，重跑机制不能掩盖真实缺陷。运行：cargo run -p integration --bin integration -- test_name；cargo nextest run --no-fail-fast --workspace test_name；真实显示模式：WARPUI_USE_REAL_DISPLAY_IN_INTEGRATION_TESTS=1 cargo run -p integration --bin integration -- test_name。
限制：仅 GUI 桌面应用；测试应保持封闭环境，不依赖开发者真实 dotfiles、主目录内容、网络或既有状态；详细安装命令与更多说明资料中暂未提供。