From 072e5d2a8f757a0c45d4474075294961ae0e89e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tor=20Arne=20Vestb=C3=B8?= Date: Thu, 5 Aug 2021 18:18:05 +0200 Subject: [PATCH] testlib: Document order of QTestResult completion functions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pick-to: 6.2 Change-Id: I34adbcc2bd02887a93cd1e86692401e840afe8bd Reviewed-by: Paul Wicking Reviewed-by: Edward Welbourne Reviewed-by: Mårten Nordheim --- src/testlib/qtestresult.cpp | 39 +++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/src/testlib/qtestresult.cpp b/src/testlib/qtestresult.cpp index 581e8bc33b..b8b6ef1e9a 100644 --- a/src/testlib/qtestresult.cpp +++ b/src/testlib/qtestresult.cpp @@ -163,6 +163,22 @@ static void clearExpectFail() QTest::expectFailComment = nullptr; } +/*! + This function is called after completing each test function, + including test functions that are not data-driven. + + For data-driven functions, this is called after each call to the test + function, with distinct data. Otherwise, this function is called once, + with currentTestData() and currentGlobalTestData() set to \nullptr. + + The function is called before the test's cleanup(), if it has one. + + For benchmarks, this will be called after each repeat of a function + (with the same data row), when the benchmarking code decides to + re-run one to get sufficient data. + + \sa finishedCurrentTestDataCleanup() +*/ void QTestResult::finishedCurrentTestData() { if (QTest::expectFailMode) @@ -177,6 +193,21 @@ void QTestResult::finishedCurrentTestData() QTestLog::clearIgnoreMessages(); } +/*! + This function is called after completing each test function, + including test functions that are not data-driven. + + For data-driven functions, this is called after each call to the test + function, with distinct data. Otherwise, this function is called once, + with currentTestData() and currentGlobalTestData() set to \nullptr. + + The function is called after the test's cleanup(), if it has one. + + For benchmarks, this is called after all repeat calls to the function + (with a given data row). + + \sa finishedCurrentTestData() +*/ void QTestResult::finishedCurrentTestDataCleanup() { // If the current test hasn't failed or been skipped, then it passes. @@ -190,6 +221,14 @@ void QTestResult::finishedCurrentTestDataCleanup() QTest::resetFailed(); } +/*! + This function is called after completing each test function, + including test functions that are data-driven. + + For data-driven functions, this is called after after all data rows + have been tested, and the data table has been cleared, so both + currentTestData() and currentGlobalTestData() will be \nullptr. +*/ void QTestResult::finishedCurrentTestFunction() { QTest::currentTestFunc = nullptr;