Long live QVERIFY_THROWS_EXCEPTION!

Use variable args macros to swallow any extra commas in the
expression. To use this, the type of the exception has to be first.
Use Eddy's suggestion for a new name to avoid breaking the old macro.

[ChangeLog][QtTest] Added QVERIFY_THROWS_EXCEPTION, replacing
QVERIFY_EXCEPTION_THROWN, which has therefore been deprecated.

Change-Id: I16825c35bae0631c5fad5a9a3ace4d6edc067f83
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

1 files changed, 20 insertions, 4 deletions

diff --git a/src/testlib/qtestcase.qdoc b/src/testlib/qtestcase.qdoc
index 2990be7d77..a9cd745438 100644
--- a/src/testlib/qtestcase.qdoc
+++ b/src/testlib/qtestcase.qdoc
@@ -158,17 +158,23 @@
    \since 5.3
 
    \relates QTest
+   \deprecated [6.3] Use \c{QVERIFY_THROWS_EXCEPTION(exceptiontype, expression)} instead.
+*/
+
+/*!
+   \macro QVERIFY_THROWS_EXCEPTION(exceptiontype, ...)
+   \since 6.3
 
-   The QVERIFY_EXCEPTION_THROWN macro executes \a expression
-   and tries to catch an exception thrown from \a expression.
+   The QVERIFY_THROWS_EXCEPTION macro executes the expression given in the variadic
+   argument and expects to catch an exception thrown from the expression.
 
    There are several possible outcomes:
 
    \list
-   \li If \a expression throws an exception that is either the same as
+   \li If the expression throws an exception that is either the same as
    \a exceptiontype or derived from \a exceptiontype, then execution will continue.
 
-   \li Otherwise, if \a expression throws no exception, or the
+   \li Otherwise, if the expression throws no exception, or the
    exception thrown derives from \c{std::exception}, then a failure
    will be recorded in the test log and the macro returns early
    (from enclosing function).
@@ -178,6 +184,16 @@
    re-thrown. This avoids problems with e.g. pthread cancellation exceptions.
    \endlist
 
+   The macro uses variadic arguments so the expression can contain commas that the
+   preprocessor considers argument separators, e.g. as in
+   \code
+   QVERIFY_THROWS_EXCEPTION(std::bad_alloc,
+   // macro arguments:      ^ exceptiontype
+                            std::vector<std::pair<int, long>>{42'000'000'000, {42, 42L}});
+   // macro arguments:      \---------- 1 ----------/  \-------- 2 --------/  \3/  \ 4 /
+   //                       \----------------------- expression -----------------------/
+   \endcode
+
    \note This macro can only be used in a test function that is invoked
    by the test framework.
 */