[{"data":1,"prerenderedAt":943},["ShallowReactive",2],{"doc-assertions":3},{"id":4,"title":5,"body":6,"description":170,"extension":934,"meta":935,"navigation":936,"path":937,"seo":938,"slug":939,"source":940,"stem":941,"__hash__":942},"docs\u002Fdocs\u002Fassertions.md","Assertion Macros",{"type":7,"value":8,"toc":924},"minimark",[9,50,54,98,111,114,117,121,131,158,161,164,226,233,253,256,259,295,300,316,338,346,373,376,383,386,406,409,429,432,457,471,496,506,509,567,596,607,616,723,726,732,758,768,771,778,781,792,797,864,867,872,917,920],[10,11,12],"blockquote",{},[13,14,15,19,20,24,25,28,29,32,33,36,37,36,40,43,44,49],"p",{},[16,17,18],"strong",{},"Catch3 compatibility reference:"," This page describes the test-writing API Catch3 shares with Catch2: the macros, such as ",[21,22,23],"code",{},"TEST_CASE"," and ",[21,26,27],{},"REQUIRE",", and the ",[21,30,31],{},"Catch::"," namespace keep Catch2's names. Headers and build names are Catch3's own (",[21,34,35],{},"\u003CProgmasoft\u002FCatch3\u002FTestMacros.hpp>",", ",[21,38,39],{},"find_package(Catch3)",[21,41,42],{},"Catch3::Catch3WithMain","). See ",[45,46,48],"a",{"href":47},"\u002Fdocs\u002Fprogmasoft-catch3\u002F","Catch3 additions"," for Progmasoft APIs.",[51,52,5],"h1",{"id":53},"assertion-macros",[13,55,56,59,62,66,68,72,74,78,80,84,86,90,92,96],{},[16,57,58],{},"Contents",[60,61],"br",{},[45,63,65],{"href":64},"#natural-expressions","Natural Expressions",[60,67],{},[45,69,71],{"href":70},"#floating-point-comparisons","Floating point comparisons",[60,73],{},[45,75,77],{"href":76},"#exceptions","Exceptions",[60,79],{},[45,81,83],{"href":82},"#matcher-expressions","Matcher expressions",[60,85],{},[45,87,89],{"href":88},"#thread-safety","Thread Safety",[60,91],{},[45,93,95],{"href":94},"#expressions-with-commas","Expressions with commas",[60,97],{},[13,99,100,101,36,104,36,107,110],{},"Most test frameworks have a large collection of assertion macros to capture all possible conditional forms (",[21,102,103],{},"_EQUALS",[21,105,106],{},"_NOTEQUALS",[21,108,109],{},"_GREATER_THAN"," etc).",[13,112,113],{},"Catch is different. Because it decomposes natural C-style conditional expressions most of these forms are reduced to one or two that you will use all the time. That said there is a rich set of auxiliary macros as well. We'll describe all of these here.",[13,115,116],{},"Most of these macros come in two forms:",[118,119,65],"h2",{"id":120},"natural-expressions",[13,122,123,124,126,127,130],{},"The ",[21,125,27],{}," family of macros tests an expression and aborts the test case if it fails.\nThe ",[21,128,129],{},"CHECK"," family are equivalent but execution continues in the same test case even if the assertion fails. This is useful if you have a series of essentially orthogonal assertions and it is useful to see all the results rather than stopping at the first failure.",[132,133,134,149],"ul",{},[135,136,137,140,141,140,145,148],"li",{},[16,138,139],{},"REQUIRE("," ",[142,143,144],"em",{},"expression",[16,146,147],{},")"," and",[135,150,151,140,154,140,156],{},[16,152,153],{},"CHECK(",[142,155,144],{},[16,157,147],{},[13,159,160],{},"Evaluates the expression and records the result. If an exception is thrown, it is caught, reported, and counted as a failure. These are the macros you will use most of the time.",[13,162,163],{},"Examples:",[165,166,171],"pre",{"className":167,"code":168,"language":169,"meta":170,"style":170},"language-cpp shiki shiki-themes github-dark","CHECK( str == \"string value\" );\nCHECK( thisReturnsTrue() );\nREQUIRE( i == 42 );\n","cpp","",[21,172,173,196,210],{"__ignoreMap":170},[174,175,178,181,185,189,193],"span",{"class":176,"line":177},"line",1,[174,179,129],{"class":180},"svObZ",[174,182,184],{"class":183},"s95oV","( str ",[174,186,188],{"class":187},"snl16","==",[174,190,192],{"class":191},"sU2Wk"," \"string value\"",[174,194,195],{"class":183}," );\n",[174,197,199,201,204,207],{"class":176,"line":198},2,[174,200,129],{"class":180},[174,202,203],{"class":183},"( ",[174,205,206],{"class":180},"thisReturnsTrue",[174,208,209],{"class":183},"() );\n",[174,211,213,215,218,220,224],{"class":176,"line":212},3,[174,214,27],{"class":180},[174,216,217],{"class":183},"( i ",[174,219,188],{"class":187},[174,221,223],{"class":222},"sDLfK"," 42",[174,225,195],{"class":183},[13,227,228,229,232],{},"Expressions prefixed with ",[21,230,231],{},"!"," cannot be decomposed. If you have a type\nthat is convertible to bool and you want to assert that it evaluates to\nfalse, use the two forms below:",[132,234,235,244],{},[135,236,237,140,240,140,242,148],{},[16,238,239],{},"REQUIRE_FALSE(",[142,241,144],{},[16,243,147],{},[135,245,246,140,249,140,251],{},[16,247,248],{},"CHECK_FALSE(",[142,250,144],{},[16,252,147],{},[13,254,255],{},"Note that there is no reason to use these forms for plain bool variables,\nbecause there is no added value in decomposing them.",[13,257,258],{},"Example:",[165,260,262],{"className":167,"code":261,"language":169,"meta":170,"style":170},"Status ret = someFunction();\nREQUIRE_FALSE(ret); \u002F\u002F ret must evaluate to false, and Catch2 will print\n                    \u002F\u002F out the value of ret if possibly\n",[21,263,264,278,290],{"__ignoreMap":170},[174,265,266,269,272,275],{"class":176,"line":177},[174,267,268],{"class":183},"Status ret ",[174,270,271],{"class":187},"=",[174,273,274],{"class":180}," someFunction",[174,276,277],{"class":183},"();\n",[174,279,280,283,286],{"class":176,"line":198},[174,281,282],{"class":180},"REQUIRE_FALSE",[174,284,285],{"class":183},"(ret);",[174,287,289],{"class":288},"sAwPA"," \u002F\u002F ret must evaluate to false, and Catch2 will print\n",[174,291,292],{"class":176,"line":212},[174,293,294],{"class":288},"                    \u002F\u002F out the value of ret if possibly\n",[296,297,299],"h3",{"id":298},"other-limitations","Other limitations",[13,301,302,303,306,307,310,311,24,313,315],{},"Note that expressions containing either of the binary logical operators,\n",[21,304,305],{},"&&"," or ",[21,308,309],{},"||",", cannot be decomposed and will not compile. The reason behind\nthis is that it is impossible to overload ",[21,312,305],{},[21,314,309],{}," in a way that\nkeeps their short-circuiting semantics, and expression decomposition\nrelies on overloaded operators to work.",[13,317,318,319,322,323,325,326,328,329,36,331,333,334,337],{},"Simple example of an issue with overloading binary logical operators\nis a common pointer idiom, ",[21,320,321],{},"p && p->foo == 2",". Using the built-in ",[21,324,305],{},"\noperator, ",[21,327,13],{}," is only dereferenced if it is not null. With overloaded\n",[21,330,305],{},[21,332,13],{}," is always dereferenced, thus causing a segfault if\n",[21,335,336],{},"p == nullptr",".",[13,339,340,341,306,343,345],{},"If you want to test expression that contains ",[21,342,305],{},[21,344,309],{},", you have two\noptions.",[347,348,349,352],"ol",{},[135,350,351],{},"Enclose it in parentheses. Parentheses force evaluation of the expression\nbefore the expression decomposition can touch it, and thus it cannot\nbe used.",[135,353,354,355,358,359,362,363,366,367,369,370,372],{},"Rewrite the expression. ",[21,356,357],{},"REQUIRE(a == 1 && b == 2)"," can always be split\ninto ",[21,360,361],{},"REQUIRE(a == 1); REQUIRE(b == 2);",". Alternatively, if this is a\ncommon pattern in your tests, think about using ",[45,364,365],{"href":82},"Matchers",".\ninstead. There is no simple rewrite rule for ",[21,368,309],{},", but I generally\nbelieve that if you have ",[21,371,309],{}," in your test expression, you should rethink\nyour tests.",[118,374,71],{"id":375},"floating-point-comparisons",[13,377,378,379,337],{},"Comparing floating point numbers is complex, and ",[45,380,382],{"href":381},"\u002Fdocs\u002Fcomparing-floating-point-numbers\u002F","so it has its own\ndocumentation page",[118,384,77],{"id":385},"exceptions",[132,387,388,397],{},[135,389,390,140,393,140,395,148],{},[16,391,392],{},"REQUIRE_NOTHROW(",[142,394,144],{},[16,396,147],{},[135,398,399,140,402,140,404],{},[16,400,401],{},"CHECK_NOTHROW(",[142,403,144],{},[16,405,147],{},[13,407,408],{},"Expects that no exception is thrown during evaluation of the expression.",[132,410,411,420],{},[135,412,413,140,416,140,418,148],{},[16,414,415],{},"REQUIRE_THROWS(",[142,417,144],{},[16,419,147],{},[135,421,422,140,425,140,427],{},[16,423,424],{},"CHECK_THROWS(",[142,426,144],{},[16,428,147],{},[13,430,431],{},"Expects that an exception (of any type) is be thrown during evaluation of the expression.",[132,433,434,446],{},[135,435,436,140,439,36,441,140,444,148],{},[16,437,438],{},"REQUIRE_THROWS_AS(",[142,440,144],{},[142,442,443],{},"exception type",[16,445,147],{},[135,447,448,140,451,36,453,140,455],{},[16,449,450],{},"CHECK_THROWS_AS(",[142,452,144],{},[142,454,443],{},[16,456,147],{},[13,458,459,460,463,464,466,467,470],{},"Expects that an exception of the ",[142,461,462],{},"specified type"," is thrown during evaluation of the expression. Note that the ",[142,465,443],{}," is extended with ",[21,468,469],{},"const&"," and you should not include it yourself.",[132,472,473,485],{},[135,474,475,140,478,36,480,140,483,148],{},[16,476,477],{},"REQUIRE_THROWS_WITH(",[142,479,144],{},[142,481,482],{},"string or string matcher",[16,484,147],{},[135,486,487,140,490,36,492,140,494],{},[16,488,489],{},"CHECK_THROWS_WITH(",[142,491,144],{},[142,493,482],{},[16,495,147],{},[13,497,498,499,306,502,505],{},"Expects that an exception is thrown that, when converted to a string, matches the ",[142,500,501],{},"string",[142,503,504],{},"string matcher"," provided (see next section for Matchers).",[13,507,508],{},"e.g.",[165,510,512],{"className":167,"code":511,"language":169,"meta":170,"style":170},"REQUIRE_THROWS_WITH( openThePodBayDoors(), ContainsSubstring( \"afraid\" ) && ContainsSubstring( \"can't do that\" ) );\nREQUIRE_THROWS_WITH( dismantleHal(), \"My mind is going\" );\n",[21,513,514,551],{"__ignoreMap":170},[174,515,516,519,521,524,527,530,532,535,538,540,543,545,548],{"class":176,"line":177},[174,517,518],{"class":180},"REQUIRE_THROWS_WITH",[174,520,203],{"class":183},[174,522,523],{"class":180},"openThePodBayDoors",[174,525,526],{"class":183},"(), ",[174,528,529],{"class":180},"ContainsSubstring",[174,531,203],{"class":183},[174,533,534],{"class":191},"\"afraid\"",[174,536,537],{"class":183}," ) ",[174,539,305],{"class":187},[174,541,542],{"class":180}," ContainsSubstring",[174,544,203],{"class":183},[174,546,547],{"class":191},"\"can't do that\"",[174,549,550],{"class":183}," ) );\n",[174,552,553,555,557,560,562,565],{"class":176,"line":198},[174,554,518],{"class":180},[174,556,203],{"class":183},[174,558,559],{"class":180},"dismantleHal",[174,561,526],{"class":183},[174,563,564],{"class":191},"\"My mind is going\"",[174,566,195],{"class":183},[132,568,569,583],{},[135,570,571,140,574,36,576,36,578,140,581,148],{},[16,572,573],{},"REQUIRE_THROWS_MATCHES(",[142,575,144],{},[142,577,443],{},[142,579,580],{},"matcher for given exception type",[16,582,147],{},[135,584,585,140,588,36,590,36,592,140,594],{},[16,586,587],{},"CHECK_THROWS_MATCHES(",[142,589,144],{},[142,591,443],{},[142,593,580],{},[16,595,147],{},[13,597,598,599,601,602,606],{},"Expects that exception of ",[142,600,443],{}," is thrown and it matches provided matcher (see the ",[45,603,605],{"href":604},"\u002Fdocs\u002Fmatchers\u002F","documentation for Matchers",").",[13,608,609],{},[142,610,611,612,615],{},"Please note that the ",[21,613,614],{},"THROW"," family of assertions expects to be passed a single expression, not a statement or series of statements. If you want to check a more complicated sequence of operations, you can use a C++11 lambda function.",[165,617,619],{"className":167,"code":618,"language":169,"meta":170,"style":170},"REQUIRE_NOTHROW([&](){\n    int i = 1;\n    int j = 2;\n    auto k = i + j;\n    if (k == 3) {\n        throw 1;\n    }\n}());\n",[21,620,621,635,651,665,684,701,711,717],{"__ignoreMap":170},[174,622,623,626,629,632],{"class":176,"line":177},[174,624,625],{"class":180},"REQUIRE_NOTHROW",[174,627,628],{"class":183},"([",[174,630,631],{"class":187},"&",[174,633,634],{"class":183},"](){\n",[174,636,637,640,643,645,648],{"class":176,"line":198},[174,638,639],{"class":187},"    int",[174,641,642],{"class":183}," i ",[174,644,271],{"class":187},[174,646,647],{"class":222}," 1",[174,649,650],{"class":183},";\n",[174,652,653,655,658,660,663],{"class":176,"line":212},[174,654,639],{"class":187},[174,656,657],{"class":183}," j ",[174,659,271],{"class":187},[174,661,662],{"class":222}," 2",[174,664,650],{"class":183},[174,666,668,671,674,676,678,681],{"class":176,"line":667},4,[174,669,670],{"class":187},"    auto",[174,672,673],{"class":183}," k ",[174,675,271],{"class":187},[174,677,642],{"class":183},[174,679,680],{"class":187},"+",[174,682,683],{"class":183}," j;\n",[174,685,687,690,693,695,698],{"class":176,"line":686},5,[174,688,689],{"class":187},"    if",[174,691,692],{"class":183}," (k ",[174,694,188],{"class":187},[174,696,697],{"class":222}," 3",[174,699,700],{"class":183},") {\n",[174,702,704,707,709],{"class":176,"line":703},6,[174,705,706],{"class":187},"        throw",[174,708,647],{"class":222},[174,710,650],{"class":183},[174,712,714],{"class":176,"line":713},7,[174,715,716],{"class":183},"    }\n",[174,718,720],{"class":176,"line":719},8,[174,721,722],{"class":183},"}());\n",[118,724,83],{"id":725},"matcher-expressions",[13,727,728,729,337],{},"To support Matchers a slightly different form is used. Matchers have ",[45,730,731],{"href":604},"their own documentation",[132,733,734,747],{},[135,735,736,140,739,36,742,140,745,148],{},[16,737,738],{},"REQUIRE_THAT(",[142,740,741],{},"lhs",[142,743,744],{},"matcher expression",[16,746,147],{},[135,748,749,140,752,36,754,140,756],{},[16,750,751],{},"CHECK_THAT(",[142,753,741],{},[142,755,744],{},[16,757,147],{},[13,759,760,761,36,763,24,765,767],{},"Matchers can be composed using ",[21,762,305],{},[21,764,309],{},[21,766,231],{}," operators.",[118,769,89],{"id":770},"thread-safety",[13,772,773,774,337],{},"Currently assertions in Catch are not thread safe.\nFor more details, along with workarounds, see the section on ",[45,775,777],{"href":776},"\u002Fdocs\u002Flimitations\u002F#thread-safe-assertions","the limitations page",[118,779,95],{"id":780},"expressions-with-commas",[13,782,783,784,787,788,791],{},"Because the preprocessor parses code using different rules than the\ncompiler, multiple-argument assertions (e.g. ",[21,785,786],{},"REQUIRE_THROWS_AS",") have\nproblems with commas inside the provided expressions. As an example\n",[21,789,790],{},"REQUIRE_THROWS_AS(std::pair\u003Cint, int>(1, 2), std::invalid_argument);","\nwill fail to compile, because the preprocessor sees 3 arguments provided,\nbut the macro accepts only 2. There are two possible workarounds.",[347,793,794],{},[135,795,796],{},"Use typedef:",[165,798,800],{"className":167,"code":799,"language":169,"meta":170,"style":170},"using int_pair = std::pair\u003Cint, int>;\nREQUIRE_THROWS_AS(int_pair(1, 2), std::invalid_argument);\n",[21,801,802,835],{"__ignoreMap":170},[174,803,804,807,810,813,816,819,822,825,828,830,832],{"class":176,"line":177},[174,805,806],{"class":187},"using",[174,808,809],{"class":180}," int_pair",[174,811,812],{"class":187}," =",[174,814,815],{"class":180}," std",[174,817,818],{"class":183},"::",[174,820,821],{"class":180},"pair",[174,823,824],{"class":183},"\u003C",[174,826,827],{"class":187},"int",[174,829,36],{"class":183},[174,831,827],{"class":187},[174,833,834],{"class":183},">;\n",[174,836,837,839,842,845,847,850,852,855,858,861],{"class":176,"line":198},[174,838,786],{"class":180},[174,840,841],{"class":183},"(",[174,843,844],{"class":180},"int_pair",[174,846,841],{"class":183},[174,848,849],{"class":222},"1",[174,851,36],{"class":183},[174,853,854],{"class":222},"2",[174,856,857],{"class":183},"), ",[174,859,860],{"class":180},"std",[174,862,863],{"class":183},"::invalid_argument);\n",[13,865,866],{},"This solution is always applicable, but makes the meaning of the code\nless clear.",[347,868,869],{"start":198},[135,870,871],{},"Parenthesize the expression:",[165,873,875],{"className":167,"code":874,"language":169,"meta":170,"style":170},"TEST_CASE_METHOD((Fixture\u003Cint, int>), \"foo\", \"[bar]\") {\n    SUCCEED();\n}\n",[21,876,877,905,912],{"__ignoreMap":170},[174,878,879,882,885,888,890,893,895,898,900,903],{"class":176,"line":177},[174,880,881],{"class":180},"TEST_CASE_METHOD",[174,883,884],{"class":183},"((Fixture",[174,886,887],{"class":187},"\u003Cint",[174,889,36],{"class":183},[174,891,892],{"class":187},"int>",[174,894,857],{"class":183},[174,896,897],{"class":191},"\"foo\"",[174,899,36],{"class":183},[174,901,902],{"class":191},"\"[bar]\"",[174,904,700],{"class":183},[174,906,907,910],{"class":176,"line":198},[174,908,909],{"class":180},"    SUCCEED",[174,911,277],{"class":183},[174,913,914],{"class":176,"line":212},[174,915,916],{"class":183},"}\n",[13,918,919],{},"This solution is not always applicable, because it might require extra\nchanges on the Catch's side to work.",[921,922,923],"style",{},"html pre.shiki code .svObZ, html code.shiki .svObZ{--shiki-default:#B392F0}html pre.shiki code .s95oV, html code.shiki .s95oV{--shiki-default:#E1E4E8}html pre.shiki code .snl16, html code.shiki .snl16{--shiki-default:#F97583}html pre.shiki code .sU2Wk, html code.shiki .sU2Wk{--shiki-default:#9ECBFF}html pre.shiki code .sDLfK, html code.shiki .sDLfK{--shiki-default:#79B8FF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .sAwPA, html code.shiki .sAwPA{--shiki-default:#6A737D}",{"title":170,"searchDepth":198,"depth":198,"links":925},[926,929,930,931,932,933],{"id":120,"depth":198,"text":65,"children":927},[928],{"id":298,"depth":212,"text":299},{"id":375,"depth":198,"text":71},{"id":385,"depth":198,"text":77},{"id":725,"depth":198,"text":83},{"id":770,"depth":198,"text":89},{"id":780,"depth":198,"text":95},"md",{},true,"\u002Fdocs\u002Fassertions",{"title":5,"description":170},"assertions","docs\u002Fassertions.md","docs\u002Fassertions","jQ1UftvtCEjo2a9l9IRfALMyooCSk_TC6SmHILR0TGw",1794961591525]