如何为 Urwid TUI 编写可靠的集成测试-Python教程-PHP中文网

如何为 Urwid TUI 编写可靠的集成测试

本文介绍如何绕过 Urwid MainLoop 的阻塞式事件循环，直接调用组件的 keypress() 方法进行可控、可断言的集成测试，重点验证输入过滤、通配符匹配与自动补全逻辑，并通过检查底层 Text 组件内容完成状态断言。

本文介绍如何绕过 urwid `mainloop` 的阻塞式事件循环，直接调用组件的 `keypress()` 方法进行可控、可断言的集成测试，重点验证输入过滤、通配符匹配与自动补全逻辑，并通过检查底层 `text` 组件内容完成状态断言。

Urwid 是一个面向终端的纯 Python TUI 框架，其核心设计依赖于 MainLoop 驱动的事件循环。这使得传统“启动→模拟按键→断言 UI 状态”的黑盒集成测试难以实施——一旦触发未处理按键（如 "a"），unhandled_input 回调会立即抛出异常（如 ValueError: STOPPED at:a），导致测试中断。根本解法不是强行驱动 MainLoop，而是跳过事件分发层，直接对目标 urwid.Edit 子类（如 InputValidationQuestion）执行单元化交互测试。

✅ 正确测试策略：白盒驱动 + 状态快照

Urwid 组件是高度可组合的纯对象。InputValidationQuestion 的行为（如过滤建议、更新自动补全框）完全由其 keypress()、update_autocomplete() 等方法控制，不依赖 MainLoop 运行时环境。因此，测试应：

实例化应用并获取目标输入控件（如 app.inputs[0]）；
直接调用 widget.keypress(size, key) —— size 可传占位值（如 1），Urwid 仅在需布局计算时使用它；
通过访问嵌套子组件断言状态：自动补全文本位于 autocomplete_box.original_widget.text；
复用业务逻辑函数辅助验证：如 get_filtered_suggestions() 可独立测试，确保与 UI 行为一致。

以下是一个完整、可运行的 Pytest 示例：

import pytest
from tui_labeller.tuis.urwid.InputValidationQuestions import InputValidationQuestions

@pytest.fixture
def app():
    return InputValidationQuestions()

def assert_autocomplete_options(widget, expected_options, step_desc):
    """断言自动补全框显示的选项是否符合预期（忽略顺序）"""
    # 深度访问：AttrMap → Text widget → text 属性
    autocomplete_text_widget = (
        widget._original_widget.autocomplete_box.original_widget
    )
    actual_text = autocomplete_text_widget.text.strip()

    if not actual_text:
        actual_options = []
    else:
        actual_options = [opt.strip() for opt in actual_text.split(",")]

    assert sorted(actual_options) == sorted(expected_options), (
        f"步骤 '{step_desc}' 后，期望选项 {sorted(expected_options)}，"
        f"实际显示 '{actual_text}'"
    )

def test_avocado_selection_via_wildcard(app):
    """测试输入 'a', '*', 't' 后，自动补全精确匹配 'apricot'"""
    question = app.inputs[0]  # 第一个输入框

    # Step 1: 输入 'a' → 应显示所有以 'a' 开头的建议
    question.keypress(1, "a")
    assert_autocomplete_options(question, ["apple", "apricot", "avocado"], "输入 'a'")

    # Step 2: 输入 '*' → 通配符，仍显示全部（因 'a*' 匹配全部）
    question.keypress(1, "*")
    assert_autocomplete_options(question, ["apple", "apricot", "avocado"], "输入 '*'")

    # Step 3: 输入 't' → 编辑文本变为 'a*t'，仅 'apricot' 匹配
    question.keypress(1, "t")
    assert_autocomplete_options(question, ["apricot"], "输入 't'")

    # ✅ 验证最终编辑文本是否已自动设为 'apricot'
    assert question._original_widget.edit_text == "apricot"

def test_enter_triggers_unhandled_input(app):
    """测试按 Enter 键时，unhandled_input 被调用并抛出预期异常"""
    question = app.inputs[0]
    question.keypress(1, "a")  # 初始化状态

    with pytest.raises(ValueError, match=r"STOPPED at:enter"):
        app.handle_input("enter")  # 直接调用 unhandled_input 处理器

⚠️ 关键注意事项

避免 loop.process_input()：该方法会强制走完整事件流，触发 unhandled_input，是测试失败的根源；
keypress() 是安全入口：它只执行当前 widget 的逻辑，不会跨组件分发（除非显式调用 super().keypress()）；
路径访问需谨慎：_original_widget 是 Urwid 内部属性（带下划线），但它是访问被 AttrMap 包裹的真实 widget 的标准方式；
通配符匹配逻辑需对齐：确保 get_filtered_suggestions() 的实现与 _match_pattern() 一致，否则 UI 行为与断言脱节；
初始化后手动触发首次补全：若测试需初始建议，调用 question._original_widget.update_autocomplete()。