TestCase QML Type

ユニットテストケースを表します。詳細...

Import Statement:	`import QtTest`
Inherits:	Item

プロパティ

completed : bool
name : string
optional : bool
running : bool
when : bool
windowShown : bool

方法

cleanup()
cleanupTestCase()
compare(actual, expected, message)
object createTemporaryObject(Component component, object parent, object properties)
object createTemporaryQmlObject(string qml, object parent, string filePath)
expectFail(tag, message)
expectFailContinue(tag, message)
fail(message)
failOnWarning(message) (since 6.3)
QtObject findChild(parent, objectName)
fuzzyCompare(actual, expected, delta, message)
object grabImage(item)
ignoreWarning(message)
init()
initTestCase()
bool isPolishScheduled(object itemOrWindow)
keyClick(key, modifiers, delay)
keyPress(key, modifiers, delay)
keyRelease(key, modifiers, delay)
keySequence(keySequence)
mouseClick(item, x, y, button, modifiers, delay)
mouseDoubleClickSequence(item, x, y, button, modifiers, delay)
mouseDrag(item, x, y, dx, dy, button, modifiers, delay)
mouseMove(item, x, y, delay, buttons)
mousePress(item, x, y, button, modifiers, delay)
mouseRelease(item, x, y, button, modifiers, delay)
mouseWheel(item, x, y, xDelta, yDelta, button, modifiers, delay)
skip(message)
sleep(ms)
TouchEventSequence touchEvent(object item)
tryCompare(obj, property, expected, timeout, message)
tryVerify(function, timeout, message)
verify(condition, message)
wait(ms)
bool waitForPolish(object windowOrItem, int timeout) (since 6.5)
waitForRendering(item, timeout)
warn(message)

詳細説明

QML テストケース入門

テストケースは、TestCase 型の中に JavaScript の関数として記述します：

import QtQuick 2.0
import QtTest 1.2

TestCase {
    name: "MathTests"

    function test_math() {
        compare(2 + 2, 4, "2 + 2 = 4")
    }

    function test_fail() {
        compare(2 + 2, 5, "2 + 2 = 5")
    }
}

test_" で始まる名前の関数は、実行されるテストケースとして扱われます。name プロパティは、出力される関数のプレフィックスとして使用されます：

********* Start testing of MathTests *********
Config: Using QTest library 4.7.2, Qt 4.7.2
PASS   : MathTests::initTestCase()
FAIL!  : MathTests::test_fail() 2 + 2 = 5
   Actual (): 4
   Expected (): 5
   Loc: [/home/.../tst_math.qml(12)]
PASS   : MathTests::test_math()
PASS   : MathTests::cleanupTestCase()
Totals: 3 passed, 1 failed, 0 skipped
********* Finished testing of MathTests *********

JavaScript のプロパティの仕組み上、テスト関数の順番は予測できません。予測しやすくするために、テストフレームワークは関数を名前の昇順に並べ替えます。これは、順番に実行しなければならないふたつのテストがある場合に役立ちます。

複数の TestCase 型を指定することができます。すべて完了すると、テストプログラムは終了します。前提条件が失敗したので）テストケースを実行する必要がない場合は、optional を true に設定します。

データ駆動型テスト

テーブルデータは、"_data" で終わる関数名を使ってテストに与えることができます。あるいは、init_data() 関数を使用して、TestCase 型の中に "_data" 関数がないすべてのテスト関数に対してデフォルトのテストデータを提供することもできます：

import QtQuick 2.0
import QtTest 1.2

TestCase {
    name: "DataTests"

    function init_data() {
      return [
           {tag:"init_data_1", a:1, b:2, answer: 3},
           {tag:"init_data_2", a:2, b:4, answer: 6}
      ];
    }

    function test_table_data() {
        return [
            {tag: "2 + 2 = 4", a: 2, b: 2, answer: 4 },
            {tag: "2 + 6 = 8", a: 2, b: 6, answer: 8 },
        ]
    }

    function test_table(data) {
        //data comes from test_table_data
        compare(data.a + data.b, data.answer)
    }

    function test_default_table(data) {
        //data comes from init_data
        compare(data.a + data.b, data.answer)
    }
}

テストフレームワークは、テーブルのすべての行を繰り返し処理し、それぞれの行をテスト関数に渡します。このように、カラムを抽出してテストに使用することができます。tag このカラムは、行が失敗したときにテストフレームワークによって出力され、それ以外のテストが成功したときに、どのケースが失敗したのかを識別しやすくします。

ベンチマーク

benchmark_" で始まる名前の関数は、Qt ベンチマークフレームワークで複数回実行されます。これは QTestLib の C++ 版でQBENCHMARK マクロを使うのと同じです。

TestCase {
    id: top
    name: "CreateBenchmark"

    function benchmark_create_component() {
        let component = Qt.createComponent("item.qml")
        let obj = component.createObject(top)
        obj.destroy()
        component.destroy()
    }
}

RESULT : CreateBenchmark::benchmark_create_component:
     0.23 msecs per iteration (total: 60, iterations: 256)
PASS   : CreateBenchmark::benchmark_create_component()

QBENCHMARK_ONCE マクロの効果を得るには、テスト関数名の前に "benchmark_once_" をつけます。

キーボードとマウスイベントのシミュレート

keyPress(),keyRelease(),keyClick() メソッドを使用すると、ユニットテスト内でキーボードイベントをシミュレートできます。イベントは現在フォーカスされている QML アイテムに送られます。Qt.Key enum 値か latin1 char (長さ 1 の文字列) を渡すことができます。

Rectangle {
    width: 50; height: 50
    focus: true

    TestCase {
        name: "KeyClick"
        when: windowShown

        function test_key_click() {
            keyClick(Qt.Key_Left)
            keyClick("a")
            ...
        }
    }
}

mousePress(),mouseRelease(),mouseClick(),mouseDoubleClickSequence(),mouseMove() メソッドも同様の方法でマウスイベントをシミュレートします。

テストで他のウィンドウを作成すると、それらのウィンドウがアクティブになり、 TestCase のウィンドウからフォーカスが奪われてしまう可能性があります。テストケースのウィンドウがアクティブであることを確認するには、以下のコードを使用します：

testCase.Window.window.requestActivate()
tryCompare(testCase.Window.window, "active", true)

注意:キーボードとマウスのイベントは、メインウィンドウが表示された後でなければ配信できません。それ以前にイベントを配信しようとすると、失敗します。when およびwindowShown プロパティを使用して、メインウィンドウがいつ表示されたかを追跡します。

動的に生成されるテストオブジェクトの管理

QML のテストの典型的なパターンは、動的に項目を作成し、テスト関数の最後でそれを破棄するというものです：

TestCase {
    id: testCase
    name: "MyTest"
    when: windowShown

    function test_click() {
        let item = Qt.createQmlObject("import QtQuick 2.0; Item {}", testCase);
        verify(item);

        // Test item...

        item.destroy();
    }
}

このパターンの問題点は、テスト関数の中で失敗があった場合、item.destroy() への呼び出しがスキップされ、テストケースが終了するまで、アイテムがシーンにぶら下がったままになってしまうことです。たとえば、入力イベントがブロックされたり、関係のないデバッグ出力が生成されたりして、コードの実行を追うのが難しくなります。

代わりにcreateTemporaryQmlObject() を呼び出すことで、テスト関数の終了時にオブジェクトが破棄されることが保証されます：

TestCase {
    id: testCase
    name: "MyTest"
    when: windowShown

    function test_click() {
        let item = createTemporaryQmlObject("import QtQuick 2.0; Item {}", testCase);
        verify(item);

        // Test item...

        // Don't need to worry about destroying "item" here.
    }
}

Component のcreateObject() 関数で作成されたオブジェクトについては、createTemporaryObject() 関数を使用することができます。

テストとアプリケーションロジックの分離

たいていの場合、テストをアプリケーションロジックから切り離したいでしょう。

たとえば、次のようなプロジェクト構成にします：

.
| — CMakeLists.txt
| — main.cpp
| - main.qml
| — MyModule
    | — MyButton.qml
    | — CMakeLists.txt
| — tests
    | — tst_testqml.qml
    | — main.cpp
    | — setup.cpp
    | — setup.h

MyModule/MyButton.qml をテストするために、MyModule/CMakeLists.txt にMyModule 用のライブラリを作成し、テストプロジェクトtests/UnitQMLTests/CMakeLists.txt にリンクします：

MyModule/CMakeLists.txt tests/CMakeLists.txt tests/main.cpp tests/setup.cpp tests/setup.h CMakeLists.txt

    ...
qt_add_library(MyModule STATIC)

qt6_add_qml_module(MyModule
    URI MyModule
    QML_FILES MyButton.qml
)
    ...

    ...
add_executable(TestMyApplication main.cpp
               setup.cpp setup.h)

add_test(NAME TestMyApplication COMMAND TestMyApplication)

target_link_libraries(TestMyApplication
    PRIVATE
        Qt6::QuickTest
        Qt6::Qml
        MyModule
        MyModuleplugin
)
    ...

#include <QtQuickTest/quicktest.h>
#include "setup.h"

QUICK_TEST_MAIN_WITH_SETUP(TestQML, Setup)

#include "setup.h"

void Setup::applicationAvailable()
{
    // custom code that doesn't require QQmlEngine
}

void Setup::qmlEngineAvailable(QQmlEngine *engine)
{
    // add import paths
}

void Setup::cleanupTestCase()
{
    // custom code to clean up before destruction starts
}

#ifndef SETUP_H
#define SETUP_H

#include <QObject>
#include <QQmlEngine>

class Setup : public QObject
{
    Q_OBJECT
public:
    Setup() = default;

public slots:
    void applicationAvailable();
    void qmlEngineAvailable(QQmlEngine *engine);
    void cleanupTestCase();
};

#endif // SETUP_H

    ...
add_subdirectory(MyModule)
add_subdirectory(tests)

qt_add_executable(MyApplication
    src/main.cpp
)

qt_add_qml_module(MyApplication
    URI MyApplication
    QML_FILES main.qml
)
    ...

次に、tests/tst_testqml.qml で、MyModule/MyButton.qml をインポートします：

tests/tst_testqml.qml MyModule/MyButton.qml

import QtQuick
import QtQuick.Controls

import QtTest
import MyModule

Item {
    width: 800
    height: 600

    MyButton {
        id: myButton
        anchors.centerIn: parent
    }

    TestCase {
        name: "MyButton"
        when: windowShown

        function test_clickToExpand() {
            const widthBeforeClick = myButton.width;
            mouseClick(myButton);
            const widthAfterClick = myButton.width;
            verify(widthBeforeClick < widthAfterClick);
        }
    }
}

import QtQuick
import QtQuick.Controls

Button {
    width: 50
    height: 50
    onClicked: width = 100
}

SignalSpy およびQt Quick Testも参照のこと。

プロパティ・ドキュメンテーション

completed : bool

このプロパティは、テストケースの実行が完了すると true に設定されます。テストケースは一度しか実行されません。初期値は false です。

running およびwhenも参照してください。

name : string

このプロパティは、結果報告用のテスト・ケースの名前を定義する。デフォルト値は空文字列です。

TestCase {
    name: "ButtonTests"
    ...
}

optional : bool

テストアプリケーションには、複数のTestCase タイプを指定することができます。すべて完了すると、アプリケーションは終了します。前提条件が失敗したため）テストケースを実行する必要がない場合は、このプロパティを true に設定できます。デフォルト値は false です。

TestCase {
    when: false
    optional: true
    function test_not_run() {
        verify(false)
    }
}

when およびcompletedも参照してください。

running : bool

このプロパティは、テストケースが実行されている間、true に設定されます。初期値は false で、テストケースが完了すると、値は再び false になります。

completed およびwhenも参照してください。

when : bool

このプロパティは、アプリケーションがテストケースの実行を希望する場合に true に設定する。デフォルト値は true です。以下の例では、ユーザーがマウスボタンを押したときにテストが実行されます：

Rectangle {
    id: foo
    width: 640; height: 480
    color: "cyan"

    MouseArea {
        id: area
        anchors.fill: parent
    }

    property bool bar: true

    TestCase {
        name: "ItemTests"
        when: area.pressed
        id: test1

        function test_bar() {
            verify(bar)
        }
    }
}

すべてのTestCase タイプがトリガされ、実行されると、テストアプリケーションは終了します。optional プロパティを使用して、TestCase タイプを除外することができます。

optional およびcompletedも参照してください。

windowShown : bool

このプロパティは、QML 表示ウィンドウが表示された後に true に設定されます。通常、テストケースはテストアプリケーションがロードされ、ウィンドウが表示される前に実行されます。テストケースに視覚的な型や動作が含まれる場合は、ウィンドウが表示された後まで遅らせる必要があるかもしれません。

Button {
    id: button
    onClicked: text = "Clicked"
    TestCase {
        name: "ClickTest"
        when: windowShown
        function test_click() {
            button.clicked();
            compare(button.text, "Clicked");
        }
    }
}

メソッドドキュメント

cleanup()

この関数は、TestCase 型で実行される各テスト関数の後に呼び出される。デフォルトの実装は何もしません。アプリケーションは、各テスト関数の後にクリーンアップを実行する独自の実装を提供することができます。

init() およびcleanupTestCase()も参照 。

cleanupTestCase()

この関数は、TestCase 型の他のすべてのテスト関数が完了した後に呼び出される。デフォルトの実装では何も行いません。アプリケーションは、テストケースのクリーンアップを行うための独自の実装を提供することができます。

initTestCase() およびcleanup()も参照 。

compare(actual, expected, message = "")

actual がexpected と同じでない場合、現在のテストケースに失敗し、オプションのmessage を表示する。C++ のQCOMPARE(actual, expected) に似ています。

tryCompare() およびfuzzyCompareも参照。

object createTemporaryObject(Component component, object parent, object properties)

この関数は、与えられたcomponent とオプションで指定されたparent およびproperties から QML オブジェクトを動的に生成します。返されたオブジェクトはcleanup() の実行が終了した後に破棄されます(まだ破棄されていない場合)。つまり、この関数で作成されたオブジェクトは、テストの失敗の有無にかかわらず、テストが終了するたびに破棄されることが保証されています。

オブジェクトの作成中にエラーがあった場合は、null が返されます。

この関数は内部的にcomponent.createObject() を呼び出す。

Managing Dynamically Created Test Objectsも参照のこと。

object createTemporaryQmlObject(string qml, object parent, string filePath)

この関数は、与えられたqml 文字列から、指定されたparent を持つ QML オブジェクトを動的に生成します。返されたオブジェクトはcleanup() の実行が終了した後に破棄されます(まだ破棄されていない場合)。つまり、この関数で作成されたオブジェクトは、テストの失敗の有無にかかわらず、テストが終わるたびに破棄されることが保証されています。

オブジェクトの作成中にエラーがあった場合は、null が返される。

filePath が指定された場合、作成されたオブジェクトのエラー報告に使用されます。

この関数は、内部的にQt.createQmlObject() を呼び出します。

Managing Dynamically Created Test Objectsも参照。

expectFail(tag, message)

データ・ドリブン・テストでは、tag に関連する行を、失敗が予想される行としてマークする。失敗が発生したら、message を表示し、テストを中止して、テストに合格マークを付けます。C++のQEXPECT_FAIL(tag, message, Abort) 。

テストがデータ駆動型でない場合は、tag を空文字列に設定する必要があります。

expectFailContinue()も参照のこと 。

expectFailContinue(tag, message)

データ・ドリブン・テストでは、tag に関連する行を、失敗が予想される行としてマークする。失敗が発生したら、message を表示し、テストを続行する。C++ のQEXPECT_FAIL(tag, message, Continue) に似ています。

テストがデータ駆動型でない場合は、tag を空文字列に設定する必要があります。

expectFail()も参照のこと 。

fail(message = "")

現在のテストケースに失敗します。オプションでmessage を指定します。C++ のQFAIL(message) に似ている。

`[since 6.3]` failOnWarning(message)

message にマッチする警告ごとに、テストの失敗をテストログに追加します。失敗が追加されると、テスト関数は実行を継続します。

message には文字列か、メッセージのパターンを指定する正規表現を指定します。後者の場合、遭遇した警告ごとに、最初にマッチしたパターンが失敗の原因となり、残りのパターンは無視されます。

すべてのパターンは、各テスト関数の最後でクリアされます。

例えば、以下のスニペットは、"Something bad happened" というテキストを含む警告が発生した場合、テストに失敗します：

failOnWarning("Something bad happened")

次のスニペットは、指定されたパターンにマッチする警告が発生した場合、テストに失敗します：

failOnWarning(/[0-9]+ bad things happened/)

与えられた警告をトリガーするすべてのテストを失敗させるには、init() でこの関数に適切な正規表現を渡します：

function init() {
    failOnWarning(/.?/)
}

注意: JavaScript の RegExp オブジェクトであるにもかかわらず、それはそのように解釈されません; 代わりに、パターンはQRegularExpression に渡されます。

注意: ignoreMessage() はこの関数より優先されるので、ignoreMessage() とfailOnWarning() の両方に与えられたパターンにマッチする警告は無視されます。

このメソッドは Qt 6.3 で導入されました。

QTest::failOnWarning() およびwarn()も参照してください 。

QtObject findChild(parent, objectName)

objectName を持つparent の最初の子、またはそのような項目が存在しない場合はnull を返す。視覚的な子と非視覚的な子の両方が再帰的に検索され、視覚的な子が最初に検索されます。

compare(findChild(item, "childObject"), expectedChildObject);

fuzzyCompare(actual, expected, delta, message = "")

actual とexpected の差がdelta より大きい場合、現在のテストケースに失敗し、オプションのmessage を表示する。C++ のqFuzzyCompare(actual, expected) と似ていますが、delta の値が必要です。

この関数は、actual とexpected の両方の値が色値に変換できる場合、色比較にも使用できます。RGBA チャンネル値の差のいずれかがdelta より大きい場合、テストは失敗します。

tryCompare() およびcompare()も参照 。

object grabImage(item)

与えられたitem のスナップショット画像オブジェクトを返します。

返される画像オブジェクトは以下のプロパティを持ちます：

width 基礎となる画像の幅を返します（5.10 以降）。
height 基礎となる画像の高さを返します（5.10 以降）。
size 基礎となる画像のサイズを返します（5.10以降）。

さらに、返される image オブジェクトには以下のメソッドがあります：

red(x, y) x,y位置のピクセルの赤チャンネルの値を返します。
green(x, y) x,y位置のピクセルの緑チャンネル値を返します。
blue(x, y) x,y位置のピクセルの青チャンネル値を返します。
alpha(x, y) x,y位置の画素のアルファチャンネル値を返します。
pixel(x, y) x,y位置の画素の色値を返します。

equals(image) この画像がimageと同一の場合はtrue を返します -QImage::operator== を参照（5.6以降）。

例えば

let image = grabImage(rect);
compare(image.red(10, 10), 255);
compare(image.pixel(20, 20), Qt.rgba(255, 0, 0, 255));

rect.width += 10;
let newImage = grabImage(rect);
verify(!newImage.equals(image));

save(path) 画像を与えられたパスに保存します。画像を保存できない場合は例外が発生します。(5.10 以降)
これは、失敗したテストの事後分析を行うときなどに便利です：
```
let image = grabImage(rect);
try {
    compare(image.width, 100);
} catch (ex) {
    image.save("debug.png");
    throw ex;
}
```

ignoreWarning(message)

message を無視された警告メッセージとしてマークする。このメッセージが発生した場合、警告は表示されず、テストはパスします。このメッセージが表示されない場合、テストは失敗します。C++ のQTest::ignoreMessage(QtWarningMsg, message) に似ています。

Qt 5.12 以降、message は文字列か、無視するメッセージのパターンを指定する正規表現にすることができます。

例えば、以下のスニペットは文字列の警告メッセージを無視します：

ignoreWarning("Something sort of bad happened")

また、次のスニペットは、いくつかの警告メッセージにマッチする正規表現を無視します：

ignoreWarning(new RegExp("[0-9]+ bad things happened"))

注： JavaScriptのRegExpオブジェクトであるにもかかわらず、それはそのように解釈されません。代わりに、パターンはQRegularExpression に渡されます。

warn()も参照してください 。

init()

この関数は、TestCase 型で実行される各テスト関数の前に呼び出される。デフォルトの実装は何もしません。アプリケーションは、各テスト関数の前に初期化を実行する独自の実装を提供できます。

cleanup() およびinitTestCase()も参照 。

initTestCase()

この関数は、TestCase 型の他のテスト関数の前に呼び出される。デフォルトの実装では何も行いません。アプリケーションは独自の実装を用意して、テストケースの初期化を行うことができます。

cleanupTestCase() およびinit()も参照 。

bool isPolishScheduled(object itemOrWindow)

itemOrWindow がItem の場合、この関数は、最後にpolish() が呼び出されて以降、updatePolish() が呼び出されていなければtrue を返し、そうでなければfalse を返します。

Qt 6.5 以降では、itemOrWindow がWindow である場合、この関数はupdatePolish() が最後にpolish() を呼び出したとき以降に、管理しているアイテムに対して呼び出されていなければtrue を返し、そうでなければfalse を返します。

QMLでプロパティに値を代入する場合、代入の結果としてアイテムが行わなければならないレイアウトの変更はすぐに反映されないかもしれません。このような場合、この関数を使用することで、テストの実行が続行される前に項目が磨かれたことを確認することができます。たとえば、次のようになります：

verify(isPolishScheduled(item))
verify(waitForItemPolished(item))

上記のisPolishScheduled() への呼び出しがない場合、waitForItemPolished() への呼び出しは、研磨が予定されていないことがわかり、そのため項目はすでに研磨されていると仮定して即座にパスするかもしれません。この関数を使用することで、なぜアイテムが磨かれなかったのかが明らかになり、そのような状況下でテストが早期に失敗するようになります。

waitForPolish()、QQuickItem::polish()、QQuickItem::updatePolish()も参照 。

keyClick(key, modifiers = Qt.NoModifier, delay = -1)

現在フォーカスされているアイテムで、オプションのmodifiers を使ってkey をクリックすることをシミュレートする。delay が 0 より大きい場合、テストはdelay ミリ秒待つ。

イベントは、TestCase ウィンドウか、複数のウィンドウの場合は、現在のアクティブなウィンドウに送られます。詳細はQGuiApplication::focusWindow （）を参照。

keyPress() およびkeyRelease()も参照の こと。

keyPress(key, modifiers = Qt.NoModifier, delay = -1)

modifiers 現在フォーカスされているアイテムで、key を押すことをシミュレートする。delay が 0 より大きい場合、テストはdelay ミリ秒待つ。

イベントは、TestCase ウィンドウか、複数のウィンドウの場合は、現在のアクティブなウィンドウに送られます。詳細はQGuiApplication::focusWindow() を参照。

注意：ある時点で、keyRelease （）を使ってキーを離す必要がある。

keyRelease() およびkeyClick()も参照してください。

keyRelease(key, modifiers = Qt.NoModifier, delay = -1)

現在フォーカスされているアイテムのmodifiers オプションでkey を解放するシミュレーションを行う。delay が 0 より大きい場合、テストはdelay ミリ秒待つ。

keyPress() およびkeyClick()も参照の こと。

keySequence(keySequence)

keySequence のタイピングをシミュレートする。キーシーケンスはstandard keyboard shortcuts のいずれかに設定することもできるし、最大4つのキー押下のシーケンスを含む文字列で記述することもできる。

各イベントは、TestCase ウィンドウに送信され、複数のウィンドウがある場合は、現在のアクティブウィンドウに送信される。詳細はQGuiApplication::focusWindow() を参照のこと。

keyPress()、keyRelease()、GNU Emacs Style Key Sequences 、Shortcut.sequenceも参照のこと。

mouseClick(item, x = item.width / 2, y = item.height / 2, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)

button modifiers itemクリックの位置はx とy で定義される。x とy が定義されていない場合、位置はitem の中心となる。delay が指定されている場合、テストはボタンを押す前とボタンを離す前に、指定されたミリ秒の間待つ。

x とy で指定された位置は、item の座標系からウィンドウ座標系に変換され、配信される。item が他のアイテムで隠されていたり、item の子アイテムがその位置を占めている場合、イベントは代わりに他のアイテムに配信されます。

mousePress(),mouseRelease(),mouseDoubleClickSequence(),mouseMove(),mouseDrag(),mouseWheel()も参照のこと 。

mouseDoubleClickSequence(item, x = item.width / 2, y = item.height / 2, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)

マウスのダブルクリックによって生成されるイベントの完全なシーケンスをシミュレートするbutton modifiers オプション付きitem 。

このメソッドは、ユーザーがダブルクリックしたときに発生する一連のマウスイベントを再現します：Press-Release-Press-DoubleClick-Release。

クリックの位置はx とy で定義されます。x とy が定義されていない場合、位置はitem の中心になります。delay が指定されている場合、テストはボタンを押す前と離す前に指定されたミリ秒の間待機します。

x とy で指定された位置は、item の座標系からウィンドウ座標系に変換され、配信される。もしitem が他のアイテムで隠されていたり、item の子アイテムがその位置を占めていたりすると、イベントは代わりに他のアイテムに配信されます。

この QML メソッドは Qt 5.5 で導入されました。

mousePress(),mouseRelease(),mouseClick(),mouseMove(),mouseDrag(),mouseWheel()も参照してください 。

mouseDrag(item, x, y, dx, dy, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)

button が押され、オプションでmodifiers が指定された状態で、item 上でマウスをドラッグすることをシミュレートする。ドラッグの初期位置はx とy で定義され、ドラッグの距離はdx とdy で定義される。delay が指定された場合、このテストはボタンを離す前に指定されたミリ秒の間待機する。

x とy で指定された位置は、item の座標系からウィンドウ座標系に変換され、配信されます。item が他のアイテムで隠されていたり、item の子がその位置を占有している場合、イベントは代わりに他のアイテムに配信されます。

mousePress(),mouseClick(),mouseDoubleClickSequence(),mouseMove(),mouseRelease(),mouseWheel()も参照のこと 。

mouseMove(item, x = item.width / 2, y = item.height / 2, delay = -1, buttons = Qt.NoButton)

x buttons Qt 6.0 以降、y とが定義されていない場合、その位置はitem の中心になります。Qt 6.0 以降、x とy が定義されていない場合、位置はitem の中心となります。

delay （ミリ秒単位）が与えられると、テストはマウスポインタを動かす前に待機します。

x とy で与えられた位置は、item の座標系からウィンドウ座標系に変換され、配信される。item が他のアイテムによって隠されていたり、item の子アイテムがその位置を占めている場合、イベントは代わりに他のアイテムに送られます。

mousePress(),mouseRelease(),mouseClick(),mouseDoubleClickSequence(),mouseDrag(),mouseWheel()も参照のこと 。

mousePress(item, x = item.width / 2, y = item.height / 2, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)

item 上のオプションmodifiers でマウスbutton を押すことをシミュレートする。位置はx とy で定義される。x またはy が定義されていない場合、位置はitem の中心となる。delay が指定されている場合、テストは押す前に指定されたミリ秒の間待つ。

x とy で指定された位置は、item の座標系からウィンドウ座標系に変換され、配信される。item が他のアイテムで隠されていたり、item の子がその位置を占めていたりすると、イベントは代わりに他のアイテムに配信されます。

mouseRelease(),mouseClick(),mouseDoubleClickSequence(),mouseMove(),mouseDrag(),mouseWheel()も参照のこと 。

mouseRelease(item, x = item.width / 2, y = item.height / 2, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)

item 上のオプションmodifiers でマウスbutton をリリースするシミュレーションを行う。リリース位置はx とy で定義される。x またはy が定義されていない場合、位置はitem の中心となる。delay が指定されている場合、テストはボタンをリリースする前に指定されたミリ秒の間待機する。

x とy で指定された位置は、item の座標系からウィンドウ座標系に変換され、配信される。item が他のアイテムで隠されていたり、item の子がその位置を占有している場合、イベントは代わりに他のアイテムに配信されます。

mousePress(),mouseClick(),mouseDoubleClickSequence(),mouseMove(),mouseDrag(),mouseWheel()も参照のこと 。

mouseWheel(item, x, y, xDelta, yDelta, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)

button が押され、オプションでmodifiers が指定された状態で、item 上のマウスホイールを回転させるシミュレーションを行う。ホイールイベントの位置はx とy で定義されます。delay が指定された場合、テストはボタンを離す前に指定されたミリ秒の間待機します。

x とy で指定された位置は、item の座標系からウィンドウの座標系に変換され、配信されます。item が他のアイテムによって隠されていたり、item の子アイテムがその位置を占めていたりすると、イベントは代わりに他のアイテムに配信されます。

xDelta とyDelta には、車輪の回転距離が8分の1度単位で格納されている。詳しくはQWheelEvent::angleDelta() を参照。

mousePress()、mouseClick()、mouseDoubleClickSequence()、mouseMove()、mouseRelease()、mouseDrag()、QWheelEvent::angleDelta()も参照のこと。

skip(message = "")

現在のテストケースをスキップし、オプションのmessage を表示します。これがデータ駆動型テストの場合は、現在の行だけがスキップされます。C++ のQSKIP(message) に似ています。

sleep(ms)

Qt イベントを処理せずにms ミリ秒スリープします。

wait() およびwaitForRendering()も参照してください 。

TouchEventSequence touchEvent(object item)

シミュレートされたタッチスクリーン(QPointingDevice)を通してタッチイベントのシーケンスを開始する。イベントはitem を含むウィンドウに配信されます。

返されたオブジェクトは、単一のQTouchEvent を通して配信されるイベントを列挙するために使用されます。タッチは、特に指定がない限り、TestCase を含むウィンドウに配信される。

Rectangle {
    width: 640; height: 480

    MultiPointTouchArea {
        id: area
        anchors.fill: parent

        property bool touched: false

        onPressed: touched = true
    }

    TestCase {
        name: "ItemTests"
        when: windowShown
        id: test1

        function test_touch() {
            let touch = touchEvent(area);
            touch.press(0, area, 10, 10);
            touch.commit();
            verify(area.touched);
        }
    }
}

TouchEventSequence::press()、TouchEventSequence::move()、TouchEventSequence::release()、TouchEventSequence::stationary()、TouchEventSequence::commit()、QInputDevice::DeviceTypeも参照のこと。

tryCompare(obj, property, expected, timeout = 5000, message = "")

obj で指定されたproperty がexpected と同じでない場合、現在のテストケースに失敗し、オプションのmessage を表示する。テストは、timeout （ミリ秒単位）に達するまで複数回再試行されます。

この関数は、プロパティが非同期イベントに基づいて値を変更するアプリケーションをテストするためのものです。同期的なプロパティ変更のテストには、compare() を使用してください。

tryCompare(img, "status", BorderImage.Ready)
compare(img.width, 120)
compare(img.height, 120)
compare(img.horizontalTileMode, BorderImage.Stretch)
compare(img.verticalTileMode, BorderImage.Stretch)

SignalSpy::wait() は、シグナルが発せられるのを待つための代替方法を提供します。

compare() およびSignalSpy::wait()も参照して ください。

tryVerify(function, timeout = 5000, message = "")

指定されたtimeout （ミリ秒単位）が経過する前にfunction がtrue に評価されない場合、現在のテストケースは失敗となる。この関数は、タイムアウトに達するまで複数回評価されます。失敗すると、オプションでmessage が表示される。

この関数は、非同期イベントに基づいて条件が変化するアプリケーションをテストするためのものです。同期的な条件変更のテストにはverify() を使用し、非同期的なプロパティ変更のテストにはtryCompare() を使用します。

たとえば、以下のコードでは、tryCompare （）を使用することはできません。なぜなら、currentItem プロパティが短期間だけnull になる可能性があるからです：

tryCompare(listView.currentItem, "text", "Hello");

その代わりに、tryVerify() を使用して、まずcurrentItem がnull でないことをチェックし、その後に通常の比較を使用することができます：

tryVerify(function(){ return listView.currentItem })
compare(listView.currentItem.text, "Hello")

verify()、compare()、tryCompare()、SignalSpy::wait()も参照 。

verify(condition, message = "")

condition が偽の場合、現在のテストケースに失敗し、オプションのmessage を表示する。C++ のQVERIFY(condition) またはQVERIFY2(condition, message) に似ています。

wait(ms)

Qt イベントを処理する間、ms ミリ秒待機します。

注意: このメソッドは正確なタイマーを使って実際の待ちを行います。待っているイベントはそうではないかもしれません。特に、アニメーションやTimer QMLタイプでは、様々な要因によって正確なタイマーと粗いタイマーのどちらかを使うことができます。粗いタイマーの場合、TestCase::wait() で使用される正確なタイマーに対して、5%程度のドリフトを期待する必要があります。しかし、オペレーティングシステムは通常、タイマーの厳密な保証を提供しないため、Qtはドリフトについて厳密な保証をすることはできません。

sleep(),waitForRendering(),Qt::TimerTypeも参照してください。

`[since 6.5]` bool waitForPolish(object windowOrItem, int timeout = 5000)

windowOrItem がアイテムの場合、この関数はtimeout ミリ秒またはisPolishScheduled(windowOrItem) がfalse を返すまで待つ。isPolishScheduled(windowOrItem) がtimeout ミリ秒以内にfalse を返した場合はtrue を返し、そうでない場合はfalse を返します。

windowOrItem がウィンドウの場合、この関数はウィンドウが管理するすべてのアイテムについて、timeout ミリ秒またはisPolishScheduled() がfalse を返すまで待ちます。isPolishScheduled() がtimeout ミリ秒以内にすべてのアイテムについてfalse を返す場合はtrue を返し、そうでない場合はfalse を返します。

このメソッドは Qt 6.5 で導入されました。

isPolishScheduled(),QQuickItem::polish(),QQuickItem::updatePolish()も参照してください 。

waitForRendering(item, timeout = 5000)

timeout ミリ秒またはレンダラーによってitem がレンダリングされるまで待ちます。timeout ミリ秒以内にitem がレンダリングされた場合は true を返し、そうでない場合は false を返します。デフォルトのtimeout の値は 5000 です。

sleep() およびwait()も参照 。

warn(message)

警告メッセージとしてmessage を表示する。C++ のqWarning(message) に似ている。

ignoreWarning()も参照のこと 。

© 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.

TestCase QML Type

プロパティ

方法

詳細説明

QML テストケース入門

データ駆動型テスト

ベンチマーク

キーボードとマウスイベントのシミュレート

動的に生成されるテストオブジェクトの管理

テストとアプリケーションロジックの分離

プロパティ・ドキュメンテーション

completed : bool

name : string

optional : bool

running : bool

when : bool

windowShown : bool

メソッド ドキュメント

cleanup()

cleanupTestCase()

compare(actual, expected, message = "")

object createTemporaryObject(Component component, object parent, object properties)

object createTemporaryQmlObject(string qml, object parent, string filePath)

expectFail(tag, message)

expectFailContinue(tag, message)

fail(message = "")

[since 6.3] failOnWarning(message)

QtObject findChild(parent, objectName)

fuzzyCompare(actual, expected, delta, message = "")

object grabImage(item)

ignoreWarning(message)

init()

initTestCase()

bool isPolishScheduled(object itemOrWindow)

keyClick(key, modifiers = Qt.NoModifier, delay = -1)

keyPress(key, modifiers = Qt.NoModifier, delay = -1)

keyRelease(key, modifiers = Qt.NoModifier, delay = -1)

keySequence(keySequence)

mouseClick(item, x = item.width / 2, y = item.height / 2, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)

mouseDoubleClickSequence(item, x = item.width / 2, y = item.height / 2, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)

mouseDrag(item, x, y, dx, dy, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)

mouseMove(item, x = item.width / 2, y = item.height / 2, delay = -1, buttons = Qt.NoButton)

mousePress(item, x = item.width / 2, y = item.height / 2, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)

mouseRelease(item, x = item.width / 2, y = item.height / 2, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)

mouseWheel(item, x, y, xDelta, yDelta, button = Qt.LeftButton, modifiers = Qt.NoModifier, delay = -1)

skip(message = "")

sleep(ms)

TouchEventSequence touchEvent(object item)

tryCompare(obj, property, expected, timeout = 5000, message = "")

tryVerify(function, timeout = 5000, message = "")

verify(condition, message = "")

wait(ms)

[since 6.5] bool waitForPolish(object windowOrItem, int timeout = 5000)

waitForRendering(item, timeout = 5000)

warn(message)

メソッドドキュメント

`[since 6.3]` failOnWarning(message)

`[since 6.5]` bool waitForPolish(object windowOrItem, int timeout = 5000)