[{"data":1,"prerenderedAt":170},["ShallowReactive",2],{"doc-usage-tips":3},{"id":4,"title":5,"body":6,"description":71,"extension":161,"meta":162,"navigation":163,"path":164,"seo":165,"slug":166,"source":167,"stem":168,"__hash__":169},"docs\u002Fdocs\u002Fusage-tips.md","Best practices for the Catch3 compatibility API",{"type":7,"value":8,"toc":155},"minimark",[9,50,54,59,62,72,80,91,96,100,112,118,125,145,149,152],[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},"best-practices-for-the-catch3-compatibility-api",[55,56,58],"h2",{"id":57},"running-tests","Running tests",[13,60,61],{},"Your tests should be run in a manner roughly equivalent with:",[63,64,69],"pre",{"className":65,"code":67,"language":68},[66],"language-text",".\u002Ftests --order=random --warn=no-assertions\n","text",[21,70,67],{"__ignoreMap":71},"",[13,73,74,75,79],{},"The ",[45,76,78],{"href":77},"\u002Fdocs\u002Fprogmasoft-runner\u002F","Catch3 runner"," runs them in parallel worker\nprocesses, retries failures once alone to tell deterministic, flaky and\norder-dependent failures apart, and fails tests whose leaf path contains no\nassertion. Random order shakes out interference between tests that run in\nthe same worker; when a test fails only after another, the runner names the\nother.",[13,81,82,83,86,87,90],{},"Interference, especially destructive interference, usually comes from\nerrors in the code under test, rather than the tests themselves. Tests that\nshare state outside the process, such as a file at a fixed path or a\ndatabase, need ",[21,84,85],{},"[!serial]"," or ",[21,88,89],{},"[!resource:NAME]","; the runner gives every\ntest its own temporary directory.",[13,92,93],{},[45,94],{"id":95},"parallel-tests",[55,97,99],{"id":98},"running-tests-in-parallel","Running tests in parallel",[13,101,102,103,106,107,111],{},"The runner already runs the tests of a binary in parallel, one worker per\nhardware thread by default (",[21,104,105],{},"--jobs","). Across machines, split the run into\n",[45,108,110],{"href":109},"\u002Fdocs\u002Fprogmasoft-runner\u002F#choosing-and-ordering-tests","shards",":",[63,113,116],{"className":114,"code":115,"language":68,"meta":71},[66],".\u002Ftests --shard=0\u002F3\n.\u002Ftests --shard=1\u002F3\n.\u002Ftests --shard=2\u002F3\n",[21,117,115],{"__ignoreMap":71},[13,119,120,121,124],{},"A test goes to the shard a stable hash of its name chooses, so the shards\ncover every test exactly once whatever the order or seed of each run. With\n",[21,122,123],{},"--shard-durations=FILE",", a JSON report or history of an earlier run, the\nshards are balanced by duration instead.",[13,126,127,128,134,135,137,138,144],{},"If you use CMake and CTest, ",[45,129,131],{"href":130},"\u002Fdocs\u002Fcmake-integration\u002F#automatic-test-registration",[21,132,133],{},"catch3_discover_tests","\nregisters each ",[21,136,23],{}," as a CTest test, and\n",[45,139,141],{"href":140},"\u002Fdocs\u002Fcmake-integration\u002F#catchshardtestscmake",[21,142,143],{},"Catch3ShardTests.cmake","\nregisters shards.",[55,146,148],{"id":147},"organizing-tests-into-binaries","Organizing tests into binaries",[13,150,151],{},"Both overly large and overly small test binaries can cause issues. Overly\nlarge test binaries have to be recompiled and relinked often, and the\nlink times are usually also long. Overly small test binaries in turn pay\nsignificant overhead from linking against Catch2 more often per compiled\ntest case, and also make it hard\u002Fimpossible to run tests in batches.",[13,153,154],{},"Because there is no hard and fast rule for the right size of a test binary,\nI recommend having 1:1 correspondence between libraries in project and test\nbinaries. (At least if it is possible, in some cases it is not.) Having\na test binary for each library in project keeps related tests together,\nand makes tests easy to navigate by reflecting the project's organizational\nstructure.",{"title":71,"searchDepth":156,"depth":156,"links":157},2,[158,159,160],{"id":57,"depth":156,"text":58},{"id":98,"depth":156,"text":99},{"id":147,"depth":156,"text":148},"md",{},true,"\u002Fdocs\u002Fusage-tips",{"title":5,"description":71},"usage-tips","docs\u002Fusage-tips.md","docs\u002Fusage-tips","YhloN6dK77SDYgSTB31Mlq8Y3EdWcoVlrEGUSEBPoqk",1794961594780]