TestCase QML Type

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

• 継承されたメンバーを含む、すべてのメンバーの一覧
• 非推奨のメンバ

プロパティ

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

方法

• cleanup()
• cleanupTestCase()
• compare(actual, expected, message)
• QtObject createTemporaryObject(Component component, QtObject parent, var properties)
• QtObject createTemporaryQmlObject(string qml, QtObject 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)
• QtObject grabImage(Item 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のプロパティの仕組み上、テスト関数が検出される順序は予測できません。予測可能性を高めるため、テストフレームワークは関数を名前の昇順で並べ替えます。これは、2つのテストを特定の順序で実行する必要がある場合に役立ちます。

複数の TestCase タイプを指定できます。すべてのテストが完了すると、テストプログラムは終了します。

データ駆動型テスト

「_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ベンチマークフレームワークを使用して複数回実行され、実行結果の平均実行時間が報告されます。これは、C++版のQTestLibで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 列挙型の値、または latin1 文字（長さ 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のウィンドウがアクティブであることを確実にするには、次のコードを使用してください：

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 にリンクします：

    ...
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 をインポートすることができます：

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 に設定されます。テストケースは 1 回のみ実行されます。初期値は false です。

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

name : string

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

TestCase {
    name: "ButtonTests"
    ...
}

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 型がトリガーされ、実行が完了すると、テストアプリケーションは終了します。

「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も参照してください 。

QtObject createTemporaryObject(Component component, QtObject parent, var properties)

この関数は、指定されたcomponent から、オプションのparent およびproperties を用いて、動的にQMLオブジェクトを作成します。返されるオブジェクトは、cleanup()の実行が完了した後（まだ破棄されていない場合）、破棄されます。つまり、この関数で作成されたオブジェクトは、テストの成否にかかわらず、各テスト終了後に確実に破棄されます。

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

この関数は内部でcomponent.createObject() を呼び出します。

Managing Dynamically Created Test Objectsも参照してください 。

QtObject createTemporaryQmlObject(string qml, QtObject 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(/.?/)
}

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

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

QtObject findChild(parent, objectName)

parent の最初の子要素を、objectName として返します。該当する要素が存在しない場合は、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()も参照してください 。

QtObject grabImage(Item item)

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

返される画像オブジェクトには、以下のプロパティがあります:

• width：基となる画像の幅を返します（バージョン 5.10 以降）
• height：基となる画像の高さを返します（バージョン 5.10 以降）
• size: 基となる画像のサイズを返します（5.10以降）

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

• 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"))

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

init()

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

cleanup() およびinitTestCase()も参照してください 。

initTestCase()

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

cleanupTestCase() およびinit()も参照してください 。

bool isPolishScheduled(object itemOrWindow)

itemOrWindow がItem である場合、この関数は、前回のpolish()の呼び出し以降、updatePolish()が呼び出されていないときはtrue を返し、そうでない場合はfalse を返します。

updatePolishQt 6.5 以降、itemOrWindow がWindow である場合、この関数は、そのアイテムに対する前回のpolish()呼び出し以降、 ()が管理するいずれのアイテムに対しても呼び出されていない場合はtrue を返し、そうでない場合はfalse を返します。

QML でプロパティに値を代入する場合、その代入の結果としてアイテムが行うべきレイアウト処理は、即座に反映されないことがあり、代わりにアイテムのポリッシュが完了するまで延期されることがあります。このような場合、この関数を使用することで、テストの実行を続行する前にアイテムのポリッシュが完了していることを確実にすることができます。例：

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

上記のisPolishScheduled() を呼び出さない場合、waitForItemPolished() の呼び出しでは、ポリッシュがスケジュールされていないと認識され、アイテムがすでにポリッシュ済みであると仮定して即座に通過してしまう可能性があります。この関数を使用することで、アイテムがポリッシュされなかった理由が明確になり、そのような状況下でテストを早期に失敗させることができます。

waitForPolish()、QQuickItem::polish()、およびQQuickItem::updatePolish()も参照してください 。

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

現在フォーカスされている項目に対して、key をクリックし、必要に応じてmodifiers を実行することをシミュレートします。delay が0より大きい場合、テストはdelay ミリ秒待機します。

key で許容される形式の詳細については、Simulating Keyboard and Mouse Events を参照してください。

イベントは、TestCase ウィンドウ、またはウィンドウが複数ある場合は現在アクティブなウィンドウに送信されます。詳細については、QGuiApplication::focusWindow() を参照してください。

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

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

現在フォーカスされている項目に対して、key キーを押下し、オプションでmodifiers を指定した操作をシミュレートします。delay が0より大きい場合、テストはdelay ミリ秒待機します。

key で許容される形式の詳細については、Simulating Keyboard and Mouse Events を参照してください。

このイベントは、TestCase ウィンドウ、またはウィンドウが複数ある場合は現在アクティブなウィンドウに送信されます。詳細については、QGuiApplication::focusWindow()を参照してください。

注：いずれの時点かでは、keyRelease() を使用してキーを解放する必要があります。

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

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

現在フォーカスされている項目に対して、key を解放し、オプションでmodifiers を指定した動作をシミュレートします。delay が0より大きい場合、テストはdelay ミリ秒待機します。

key の有効な形式に関する詳細については、Simulating Keyboard and Mouse Events を参照してください。

イベントは、TestCase ウィンドウ、またはウィンドウが複数ある場合は現在アクティブなウィンドウに送信されます。詳細については、QGuiApplication::focusWindow() を参照してください。

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)

item 上で、button によるマウスクリックをシミュレートします。オプションでmodifiers を指定することも可能です。クリック位置は、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)

item 上で、マウスのダブルクリック（button ）によって生成される一連のイベントを、オプションでmodifiers を適用してシミュレートします。

このメソッドは、ユーザーがダブルクリックを行った際に生成されるマウスイベントのシーケンス（押下-離し-押下-ダブルクリック-離し）を再現します。

クリックの位置は、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 キーを押した状態で、item 上でマウスをドラッグする動作をシミュレートします。オプションでmodifiers も指定可能です。ドラッグの開始位置は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 item buttons および で指定された位置に移動します。Qt 6.0以降、 および が定義されていない場合、位置は の中心となります。y 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 上で、button へのマウスクリックをシミュレートします。オプションでmodifiers を指定することも可能です。位置は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 上で、button によるマウスボタンの離し動作をシミュレートします。オプションでmodifiers を指定することもできます。ボタンを離す位置は、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 には、ホイールの回転距離が 1 度の 8 分の 1 単位で格納されています。詳細については、QWheelEvent::angleDelta() を参照してください。

関連項目： mousePress()、mouseClick()、mouseDoubleClickSequence()、mouseMove()、mouseRelease()、mouseDrag()、およびQWheelEvent::angleDelta()も参照してください 。

skip(message = "")

現在のテストケースをスキップし、オプションでmessage を出力します。データ駆動型テストの場合、現在の行のみがスキップされます。C++のQSKIP(message) と同様です。

sleep(ms)

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

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()` を使用してください。

たとえば、以下のコードでは、currentItem プロパティが短時間だけnull になる可能性があるため、tryCompare() を使用することはできません:

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 がfalseの場合、現在のテストケースを失敗とし、オプションでmessage を表示します。C++のQVERIFY(condition) やQVERIFY2(condition, message) と同様です。

wait(ms)

Qtイベントの処理中に、ms ミリ秒待機します。

sleep()、waitForRendering()、およびQt::TimerTypeも参照してください 。

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

windowOrItem がItemの場合、この関数はtimeout ミリ秒間待機するか、isPolishScheduled(windowOrItem) がfalse を返すまで待機します。isPolishScheduled(windowOrItem) がtimeout ミリ秒以内にfalse を返した場合はtrue を返し、それ以外の場合はfalse を返します。

windowOrItem がWindowの場合、この関数はtimeout ミリ秒間待機するか、またはisPolishScheduled() が、そのウィンドウによって管理されるすべての項目についてfalse を返すまで待機します。isPolishScheduled() がtimeout ミリ秒以内にすべての項目についてfalse を返した場合、true を返します。それ以外の場合はfalse を返します。

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

isPolishScheduled()、QQuickItem::polish()、およびQQuickItem::updatePolish()も参照してください 。

waitForRendering(item, timeout = 5000)

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

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

warn(message)

警告メッセージとして「message 」を出力します。C++のqWarning(message) と同様です。

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