MCP TUI测试
类似于剧作家，但适用于终端用户界面
MCP（模型上下文协议）服务器，使AI助手能够测试终端用户界面（TUI）应用程序。此服务器提供以编程方式启动、交互和验证TUI应用程序的工具。
📚 查看文档
特性
- 双重测试模式：在流模式（用于CLI工具）或缓冲模式（用于具有位置感知的完整TUI）之间进行选择
- 启动TUI应用程序：启动任何具有可配置维度的基于终端的应用程序
- 发送键盘输入：模拟用户打字、特殊按键和控制组合
- 捕获屏幕输出：读取并分析当前终端显示
- 基于位置的测试：验证特定屏幕坐标处的文本（缓冲模式）
- 光标跟踪：实时监控光标位置（缓冲模式）
- 等待文本：异步等待特定内容出现
- 断言：验证输出中是否存在预期内容
- 会话管理：同时运行多个TUI应用程序
测试模式
流模式（默认）
- 最适合：CLI工具、命令行应用程序、简单的交互式程序
- 用途：pexpect用于基于流的测试
- 功能：文本匹配、模式等待、输出捕获
- 示例用例：git、npm、grep、交互式shell脚本
缓冲区模式
- 最适合：完整的TUI应用程序、ncurses应用程序、对话框、菜单
- 用途：pexpect+pyte用于屏幕缓冲区仿真
- 功能：所有流功能加上基于位置的断言、光标跟踪、区域提取
- 示例用例：htop、vim、对话框、交互式菜单
何时使用哪种模式：
- 使用 流模式 适用于按顺序输出文本的应用程序
- 使用 缓冲模式 适用于通过光标移动绘制复杂UI的应用程序
安装
先决条件
- Python 3.10或更高版本
- 紫外线
再进行
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt或者安装软件包：
uv venv
source .venv/bin/activate
uv pip install -e .用法
运行MCP服务器
python server.py或者，如果作为软件包安装：
mcp-tui-test在Claude桌面中配置
将此添加到您的 claude_desktop_config.json:
{
"mcpServers": {
"tui-test": {
"command": "python",
"args": ["/path/to/mcp-tui-test/server.py"]
}
}
}或者，如果作为软件包安装：
{
"mcpServers": {
"tui-test": {
"command": "mcp-tui-test"
}
}
}可用工具
launch_tui
启动TUI应用程序进行测试。
参数：
command（必填）：启动TUI应用程序的命令session_id（可选）：此会话的唯一标识符（默认值：“default”）timeout（可选）：命令超时时间（秒）（默认值：30）dimensions（可选）：端子尺寸为WIDTHxHEIGHT（默认值：“80x24”）mode（可选）：测试模式-“流”或“缓冲区”（默认：“流”）
示例：
# Stream mode for CLI tools
launch_tui(command="python example_tui_app.py", session_id="test1")
# Buffer mode for full TUI applications
launch_tui(command="htop", session_id="test2", mode="buffer", dimensions="120x40")send_keys
将键盘输入发送到TUI应用程序。
参数：
keys（必填）：要发送的密钥。使用\n对于Enter，\t对于Tab，\x1b逃离session_id（可选）：会话标识符（默认值：“默认”）delay（可选）：发送密钥后的延迟秒数（默认值：0.1）
例子：
send_keys(keys="1\n", session_id="test1")send_ctrl
向TUI应用程序发送Ctrl+组合键。
参数：
key（必填）：与Ctrl组合的键（例如，“c”、“d”、“z”）session_id（可选）：会话标识符（默认值：“默认”）
例子：
send_ctrl(key="c", session_id="test1")capture_screen
捕获TUI应用程序的当前屏幕输出。
参数：
session_id（可选）：会话标识符（默认值：“默认”）include_ansi（可选）：是否在流模式中包含ANSI转义码（默认值：False）use_buffer（可选）：强制缓冲/流模式。自动检测是否为无（默认值：无）
示例：
# Auto-detect mode based on session
capture_screen(session_id="test1")
# Force buffer mode capture
capture_screen(session_id="test1", use_buffer=True)expect_text
等待TUI输出中出现特定文本。
参数：
pattern（必填）：要等待的文本或正则表达式模式session_id（可选）：会话标识符（默认值：“默认”）timeout（可选）：最长等待时间（秒）（默认值：10）
例子：
expect_text(pattern="Welcome", session_id="test1", timeout=5)assert_contains
断言当前屏幕包含特定文本。
参数：
text（必填）：在当前屏幕中搜索的文本session_id（可选）：会话标识符（默认值：“默认”）use_buffer（可选）：检查缓冲区/流模式。自动检测是否为无（默认值：无）
例子：
assert_contains(text="Counter value: 1", session_id="test1")assert_at_position （仅缓冲模式）
断言特定文本出现在屏幕位置。
参数：
text（必填）：在位置验证的文本row（必填）：行号（0索引）col（必填）：列号（0索引）session_id（可选）：会话标识符（默认值：“默认”）
例子：
# Verify "Error" appears at row 5, column 10
assert_at_position(text="Error", row=5, col=10, session_id="test1")get_cursor_position （仅缓冲模式）
获取当前光标位置。
参数：
session_id（可选）：会话标识符（默认值：“默认”）
例子：
get_cursor_position(session_id="test1")
# Returns: "Cursor position (session: test1): row 10, column 25"get_screen_region （仅缓冲模式）
提取屏幕的矩形区域。
参数：
row_start（必填）：起始行（0索引，包括0索引）row_end（必填）：结束行（0索引，不包括）col_start（可选）：起始列（0索引，包括0索引，默认值：0）col_end（可选）：结束列（0索引，独占，默认：行尾）session_id（可选）：会话标识符（默认值：“默认”）
例子：
# Extract rows 5-10, full width
get_screen_region(row_start=5, row_end=10, session_id="test1")
# Extract rows 5-10, columns 20-60
get_screen_region(row_start=5, row_end=10, col_start=20, col_end=60, session_id="test1")get_line （仅缓冲模式）
从屏幕缓冲区获取特定行。
参数：
row（必填）：行号（0索引）session_id（可选）：会话标识符（默认值：“默认”）
例子：
get_line(row=3, session_id="test1")
# Returns: "Line 3 (session: test1): [line content]"close_session
结束TUI测试会话。
参数：
session_id（可选）：会话标识符（默认值：“默认”）
例子：
close_session(session_id="test1")list_sessions
列出所有活动的TUI测试会话。
例子：
list_sessions()示例测试场景
以下是如何使用此MCP测试TUI应用程序：
- 启动应用程序:
launch_tui(command="python example_tui_app.py")- 等待加载:
expect_text(pattern="Welcome to the Example TUI Application")- 与它互动:
send_keys(keys="1\n")- 验证输出:
assert_contains(text="Hello, TUI Tester!")- 清理:
close_session()测试示例应用程序
此存储库包括一个示例TUI应用程序(example_tui_app.py)您可以使用它来测试MCP服务器。
直接运行它：
python example_tui_app.py或者通过MCP进行测试：
launch_tui(command="python example_tui_app.py")
send_keys(keys="1\n")
capture_screen()用例
- 自动化测试：验证TUI应用程序是否正常运行
- 集成测试：测试命令行工具和交互式CLI
- 文档：从TUI应用程序生成屏幕截图和示例
- 调试：在开发过程中检查TUI应用程序的状态
- CI/CD：将TUI测试添加到您的持续集成管道中
技术细节
此MCP服务器使用：
- FastMCP：用于MCP服务器实现
- pexpect：用于生成和控制终端应用程序
- pyte：用于终端仿真和屏幕缓冲区管理（缓冲模式）
- ScreenSession包装器：结合pexpect和pyte进行混合测试
建筑
- 流模式：pexpect直接捕获输出流
- 缓冲区模式：pespect输出→ pyte终端仿真器→ 屏幕缓冲区
- 自动检测：工具根据会话自动使用适当的模式
局限性
- 目前为类Unix系统（Linux、macOS）设计
- Windows支持可能需要修改（考虑使用
winpty或类似） - TUI中的鼠标支持目前不可用
- 缓冲模式需要稍多的内存用于屏幕模拟
- 基于位置的断言仅在缓冲区模式下工作
贡献
欢迎投稿！请随时提交问题或拉取请求。
许可证
MIT许可证-有关详细信息，请参阅许可证文件
相关项目
作者
为在人工智能的帮助下测试TUI应用程序而创建。