如何对QtQuick TapHandler的双击操作进行单元测试？

被测试组件（TapHandlerUnderTest） #

import QtQuick
import QtQuick.Controls

TapHandler {
    required property ApplicationWindow appWindow

    onDoubleTapped: {
        console.warn('double tapped')
        appWindow.toggleMaximized()
    }

    onSingleTapped: {
        console.warn('single tapped')
    }
}

测试用例代码 #

import QtQuick
import QtQuick.Controls
import QtTest

Item {
    id: testHelper
    width: 400
    height: 400

    property bool toggleMaximizedCalled: false

    property var appWindow: ApplicationWindow {
        function toggleMaximized() {
            testHelper.toggleMaximizedCalled = true
        }
    }

    TapHandlerUnderTest {
        id: objectUnderTest
        appWindow: testHelper.appWindow
    }

    TestCase {
        name: "TapHandlerUnderTest"
        when: windowShown

        function cleanup() {
            testHelper.toggleMaximizedCalled = false
        }

        function test_tap_data() {
            return [
                { taps: 2, called: true, tag: '2x' },
            ]
        }

        function test_tap(data) {
            mouseDoubleClickSequence(testHelper)
            compare(testHelper.toggleMaximizedCalled, data.called)
        }
    }
}

已尝试的操作及结果 #

• 使用mouseDoubleClickSequence：测试失败，日志输出两次single tapped，toggleMaximizedCalled始终为false
• 连续调用两次mouseClick：结果与上述一致
• 使用touchEvent：无任何响应，连单击事件都无法识别

问题：这是Qt的Bug吗？还是存在正确的双击测试方法？已设置export QT_QPA_PLATFORM=xcb，更换其他平台参数也没有变化。

问题分析与解决方案 #

核心原因 #

TapHandler的双击识别依赖两个关键阈值：

1. 双击间隔时间（doubleTapInterval，默认取系统设置，通常500ms）：两次点击必须在该时间内完成
2. 双击距离限制（doubleTapDistance，默认10px）：两次点击的坐标偏差不能超过该值

QtTest默认的mouseDoubleClickSequence或连续mouseClick，可能因为间隔不匹配、坐标偏差，或者事件未正确传递到TapHandler，导致只触发单击事件。

修正后的测试用例 #

import QtQuick
import QtQuick.Controls
import QtTest

Item {
    id: testHelper
    width: 400
    height: 400
    focus: true // 确保能接收鼠标事件

    property bool toggleMaximizedCalled: false

    property var appWindow: ApplicationWindow {
        function toggleMaximized() {
            testHelper.toggleMaximizedCalled = true
        }
    }

    TapHandlerUnderTest {
        id: objectUnderTest
        appWindow: testHelper.appWindow
        parent: testHelper
        doubleTapInterval: 300 // 显式设置双击间隔，方便测试控制
        doubleTapDistance: 10 // 显式设置允许的坐标偏差
    }

    TestCase {
        name: "TapHandlerUnderTest"
        when: windowShown

        function cleanup() {
            testHelper.toggleMaximizedCalled = false
        }

        function test_doubleTapTriggered() {
            // 两次点击同一坐标，间隔略小于TapHandler的双击间隔
            mouseClick(testHelper, 200, 200, Qt.LeftButton, 0)
            wait(objectUnderTest.doubleTapInterval - 50)
            mouseClick(testHelper, 200, 200, Qt.LeftButton, 0)
            
            // 等待事件循环处理双击判断逻辑
            wait(150)
            compare(testHelper.toggleMaximizedCalled, true)
        }
    }
}

关键调整点 #

1. 给testHelper设置focus: true，确保它能优先接收鼠标事件
2. 显式设置TapHandler的doubleTapInterval和doubleTapDistance，避免依赖系统默认值导致的不一致
3. 两次点击使用同一坐标，确保在doubleTapDistance范围内
4. 使用wait()控制点击间隔，确保在doubleTapInterval内完成两次点击
5. 最后等待一小段时间，让TapHandler完成双击事件的判断和处理

额外排查点 #

• 确认TapHandler的enabled属性为true（默认是true）
• 检查Qt版本：Qt 5.12及以下可能存在TapHandler测试的兼容性问题，建议升级到Qt 5.15 LTS或Qt 6.x版本
• 如果使用触摸事件测试，需要确保测试环境支持触摸模拟，并且TapHandler的acceptedDevices包含TouchScreen

内容的提问来源于stack exchange，提问作者trin94