用途:为 Textual TUI 应用编写功能测试,基于内置测试框架,通过 App.run_test() 在无头模式下运行应用(无终端输出,其余行为一致)。
主要能力:完整的 Pilot API。鼠标方面支持 click(按选择器、组件类型或实例、绝对坐标、带 shift/control/meta 修饰键、times 多次点击)、double_click、triple_click、hover、mouse_down/mouse_up 拖放;键盘方面支持 press 单键、多键序列、字符串解包输入、特殊键(tab/enter/escape/方向键/功能键等)与 ctrl+c、ctrl+shift+p 等组合;还提供 pause 等待消息队列、wait_for_animation、wait_for_scheduled_animations、exit(result=...)、resize_terminal 与 workers.wait_for_complete()。可通过 pilot.app.query_one/query 查询组件并按 CSS 选择器、类型或实例断言状态。
使用方式:测试函数必须为 async def;在 pytest 的 pyproject.toml 中设置 asyncio_mode = "auto" 可免去 @pytest.mark.asyncio;所有 pilot 方法均需 await。典型流程为 async with app.run_test() as pilot,交互后 await pilot.pause(),再对组件状态断言;可用 size=(80, 24) 指定终端尺寸。
适用场景:按钮点击、文本输入、键盘绑定、后台 Worker、响应式布局与终端尺寸变化等测试。
限制与注意:所有测试函数须为 async def,pilot 方法均需 await;交互后须加 pause 再断言;Worker 结果需 wait_for_complete;动画状态建议 wait_for_animation。相关技能:textual-snapshot-testing、textual-test-fixtures、textual-test-patterns。其他细节暂未提供。