QQuickTest Namespace
QQuickTest 命名空间包含所有与Qt Quick Test 相关的函数和宏。更多内容...
| Header: | #include <QtQuickTest> |
函数
| bool | qIsPolishScheduled(const QQuickItem *item) |
(since 6.4) bool | qIsPolishScheduled(const QQuickWindow *window) |
(since 6.4) bool | qWaitForPolish(const QQuickItem *item, int timeout = defaultTimeout) |
(since 6.4) bool | qWaitForPolish(const QQuickWindow *window, int timeout = defaultTimeout) |
宏
(since 6.10) | QTRY_VERIFY_ACTIVE_FOCUS(item) |
| QUICK_TEST_MAIN(name) | |
| QUICK_TEST_MAIN_WITH_SETUP(name, QuickTestSetupClass) | |
(since 6.10) | QVERIFY_ACTIVE_FOCUS(item) |
详细说明
有关如何编写Qt Quick 单元测试的信息，请参阅《Qt Quick Test 入门指南》。
要链接到Qt Quick Test C++ 库，请参阅 Qt Quick Test C++ API。
另请参阅 “在 QML 测试之前执行 C++”。
函数文档
bool QQuickTest::qIsPolishScheduled(const QQuickItem *item)
如果自上次调用polish() 以来，尚未在item 上调用updatePolish()，则返回true ；否则返回false 。
在 QML 中为属性赋值时，该赋值操作可能引发的任何布局调整不会立即生效，而是会被推迟至该项完成“polish”操作之后。对于此类情况，您可以使用此函数来确保在继续执行测试之前，该项已完成“polish”操作。例如：
QVERIFY(QQuickTest::qIsPolishScheduled(item));
QVERIFY(QQuickTest::qWaitForItemPolished(item));如果省略上述对 `qIsPolishScheduled() ` 的调用，对 `qWaitForItemPolished() ` 的调用可能会发现未安排任何抛光操作，从而立即通过测试——前提是该项已被抛光。此函数能明确说明项未被抛光的原因，并允许测试在此类情况下尽早失败。
该函数在 QML 中的对应实现是isPolishScheduled()。
另请参阅 QQuickItem::polish() 和QQuickItem::updatePolish()。
[since 6.4] bool QQuickTest::qIsPolishScheduled(const QQuickWindow *window)
如果该窗口管理的任何项目在调用 `qIsPolishScheduled(item) ` 时返回 `true`，则返回 `true `；否则返回 `false`。
例如，如果场景中的某个项目可能已打磨，也可能未打磨，但你需要在已打磨时等待它，可以使用以下代码：
if (QQuickTest::qIsPolishScheduled(window))
QVERIFY(QQuickTest::qWaitForPolish(window));该函数在 QML 中的等效实现是 `isPolishScheduled()`。
该函数重载了QQuickTest::qIsPolishScheduled()。
该函数在 Qt 6.4 中引入。
另请参阅 QQuickItem::polish()、QQuickItem::updatePolish() 和QQuickTest::qWaitForPolish()。
[since 6.4] bool QQuickTest::qWaitForPolish(const QQuickItem *item, int timeout = defaultTimeout)
等待timeout 毫秒，或者直到对item 调用updatePolish()为止。
item 如果updatePolish() 在timeout 毫秒内被调用，则返回true ；否则返回false 。
该函数在 Qt 6.4 中引入。
另请参阅 QQuickItem::polish()、QQuickItem::updatePolish() 和QQuickTest::qIsPolishScheduled()。
[since 6.4] bool QQuickTest::qWaitForPolish(const QQuickWindow *window, int timeout = defaultTimeout)
等待timeout 毫秒，或者直到qIsPolishScheduled(item) 对window 管理的所有项目均返回false 。
如果qIsPolishScheduled(item) 在timeout 毫秒内对所有项返回 false，则返回true ；否则返回false 。
该函数在 QML 中的等效实现是waitForPolish()。
该函数在 Qt 6.4 中引入。
另请参阅 QQuickItem::polish()、QQuickItem::updatePolish() 和QQuickTest::qIsPolishScheduled()。
宏文档
[since 6.10] QTRY_VERIFY_ACTIVE_FOCUS(item)
该宏执行的检查与QVERIFY_ACTIVE_FOCUS 配合item 所执行的检查相同，但会反复进行，直到条件为真或达到超时（以毫秒为单位）为止。每次评估之间，系统会处理事件。如果达到超时，测试日志中将记录一次失败，且测试将不再继续执行。
注意：此宏 仅可在由测试框架调用的测试函数中使用。
该宏于 Qt 6.10 版本中引入。
QUICK_TEST_MAIN(name)
设置Qt Quick Test 应用程序的入口点。name 参数用于唯一标识这组测试。
#include <QtQuickTest>
QUICK_TEST_MAIN(example)注意： 除非设置了QUICK_TEST_SOURCE_DIR 环境变量，否则该宏 默认假设您的测试源文件位于当前目录中。
另请参阅 QUICK_TEST_MAIN_WITH_SETUP() 和运行Qt Quick 测试。
QUICK_TEST_MAIN_WITH_SETUP(name, QuickTestSetupClass)
设置Qt Quick Test 应用程序的入口点。name 参数用于唯一标识这组测试。
该宏与QUICK_TEST_MAIN() 完全相同，唯一的区别在于它额外接受一个参数QuickTestSetupClass ，该参数指定将要实例化的QObject 派生类的类型。通过此类，可以定义在运行 QML 测试之前执行的额外准备代码。
注意： 除非设置了QUICK_TEST_SOURCE_DIR 环境变量，否则该宏 默认假设您的测试源文件位于当前目录下。
以下代码片段演示了该宏的使用方法：
// src_qmltest_qquicktest.cpp
#include <QtQuickTest>
#include <QQmlEngine>
#include <QQmlContext>
#include <QGuiApplication>
class Setup : public QObject
{
Q_OBJECT
public:
Setup() {}
public slots:
void applicationAvailable()
{
// Initialization that only requires the QGuiApplication object to be available
}
void qmlEngineAvailable(QQmlEngine *engine)
{
// Initialization requiring the QQmlEngine to be constructed
engine->rootContext()->setContextProperty("myContextProperty", QVariant(true));
}
void cleanupTestCase()
{
// Implement custom resource cleanup
}
};
QUICK_TEST_MAIN_WITH_SETUP(mytest, Setup)
#include "src_qmltest_qquicktest.moc"另请参阅 QUICK_TEST_MAIN() 以及运行Qt Quick 测试。
[since 6.10] QVERIFY_ACTIVE_FOCUS(item)
检查item （该类必须继承自QQuickItem ）是否具有active focus 。如果具有，则继续执行；否则，将在测试日志中记录失败信息，且测试将不再继续执行。失败消息包含与故障原因诊断相关的、针对特定焦点的信息。
注意：此宏 仅可在由测试框架调用的测试函数中使用。
该宏于 Qt 6.10 版本中引入。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
