diff --git a/bazaar/UnitTest++/UnitTest++.upp b/bazaar/UnitTest++/UnitTest++.upp index 14229b6b2..41c591ca0 100644 --- a/bazaar/UnitTest++/UnitTest++.upp +++ b/bazaar/UnitTest++/UnitTest++.upp @@ -1,60 +1,61 @@ -optimize_speed; - -uses - Core; - -file - src readonly separator, - AssertException.cpp, - Test.cpp, - Checks.cpp, - DeferredTestReporter.cpp, - DeferredTestResult.cpp, - MemoryOutStream.cpp, - ReportAssert.cpp, - TestDetails.cpp, - TestList.cpp, - TestReporter.cpp, - TestReporterStdout.cpp, - TestResults.cpp, - TestRunner.cpp, - TimeConstraint.cpp, - XmlTestReporter.cpp, - AssertException.h, - CheckMacros.h, - Checks.h, - Config.h, - DeferredTestReporter.h, - DeferredTestResult.h, - MemoryOutStream.h, - ReportAssert.h, - Test.h, - TestDetails.h, - TestList.h, - TestMacros.h, - TestReporter.h, - TestReporterStdout.h, - TestResults.h, - TestRunner.h, - TestSuite.h, - TimeConstraint.h, - TimeHelpers.h, - UnitTest++.h, - XmlTestReporter.h, - "src posix" readonly separator, - Posix/SignalTranslator.cpp, - Posix/TimeHelpersPosix.cpp, - Posix/SignalTranslator.h, - Posix/TimeHelpersPosix.h, - "src win32" readonly separator, - Win32/TimeHelpersWin32.cpp, - Win32/TimeHelpersWin32.h, - Docs readonly separator, - docs/UnitTest++.html, - COPYING, - README, - README.original; - -mainconfig - "" = ""; - +optimize_speed; + +uses + Core; + +file + src readonly separator, + AssertException.cpp, + Test.cpp, + Checks.cpp, + DeferredTestReporter.cpp, + DeferredTestResult.cpp, + MemoryOutStream.cpp, + ReportAssert.cpp, + TestDetails.cpp, + TestList.cpp, + TestReporter.cpp, + TestReporterStdout.cpp, + TestResults.cpp, + TestRunner.cpp, + TimeConstraint.cpp, + XmlTestReporter.cpp, + AssertException.h, + CheckMacros.h, + Checks.h, + Config.h, + DeferredTestReporter.h, + DeferredTestResult.h, + MemoryOutStream.h, + ReportAssert.h, + Test.h, + TestDetails.h, + TestList.h, + TestMacros.h, + TestReporter.h, + TestReporterStdout.h, + TestResults.h, + TestRunner.h, + TestSuite.h, + TimeConstraint.h, + TimeHelpers.h, + UnitTest++.h, + XmlTestReporter.h, + "src posix" readonly separator, + Posix/SignalTranslator.cpp, + Posix/TimeHelpersPosix.cpp, + Posix/SignalTranslator.h, + Posix/TimeHelpersPosix.h, + "src win32" readonly separator, + Win32/TimeHelpersWin32.cpp, + Win32/TimeHelpersWin32.h, + Docs readonly separator, + srcdoc.tpp, + docs/UnitTest++.html, + COPYING, + README, + README.original; + +mainconfig + "" = ""; + diff --git a/bazaar/UnitTest++/srcdoc.tpp/UnitTestpp$en-us.tpp b/bazaar/UnitTest++/srcdoc.tpp/UnitTestpp$en-us.tpp new file mode 100644 index 000000000..f77b05f1b --- /dev/null +++ b/bazaar/UnitTest++/srcdoc.tpp/UnitTestpp$en-us.tpp @@ -0,0 +1,325 @@ +topic "UnitTest++ in brief"; +[2 $$0,0#00000000000000000000000000000000:Default] +[l288;i1120;a17;O9;~~~.1408;2 $$1,0#10431211400427159095818037425705:param] +[a83;*R6 $$2,5#31310162474203024125188417583966:caption] +[H4;b83;*4 $$3,5#07864147445237544204411237157677:title] +[i288;O9;C2 $$4,6#40027414424643823182269349404212:item] +[b42;a42;2 $$5,5#45413000475342174754091244180557:text] +[l288;b17;a17;2 $$6,6#27521748481378242620020725143825:desc] +[l321;C@5;1 $$7,7#20902679421464641399138805415013:code] +[b2503;2 $$8,0#65142375456100023862071332075487:separator] +[*@(0.0.255)2 $$9,0#83433469410354161042741608181528:base] +[C2 $$10,0#37138531426314131251341829483380:class] +[l288;a17;*1 $$11,11#70004532496200323422659154056402:requirement] +[i417;b42;a42;O9;~~~.416;2 $$12,12#10566046415157235020018451313112:tparam] +[b167;C2 $$13,13#92430459443460461911108080531343:item1] +[i288;a42;O9;C2 $$14,14#77422149456609303542238260500223:item2] +[*@2$(0.128.128)2 $$15,15#34511555403152284025741354420178:NewsDate] +[l321;*C$7;2 $$16,16#03451589433145915344929335295360:result] +[l321;b83;a83;*C$7;2 $$17,17#07531550463529505371228428965313:result`-line] +[l160;*C+117 $$18,5#88603949442205825958800053222425:package`-title] +[2 $$19,0#53580023442335529039900623488521:gap] +[C2 $$20,20#70211524482531209251820423858195:class`-nested] +[b50;2 $$21,21#03324558446220344731010354752573:Par] +[b83;a83;*R+117 $$22,22#15150040393549804420528261439571:caption2] +[{_}%EN-US +[s2; UnitTest`+`+ in brief&] +[s0; &] +[s3; Introduction&] +[s21; For background, goals and license details, see:&] +[s21;i150;O0; [^http`:`/`/unittest`-cpp`.sourceforge`.net`/^ The UnitTest`+`+ +home page]&] +[s0;i150;O0; [^http`:`/`/www`.gamesfromwithin`.com`/articles`/0603`/000108`.html^ Noel +Llopis`' announcement]&] +[s21; The documentation, while sparse, aims to be practical, so it +should give you enough info to get started using UnitTest`+`+ +as fast as possible.&] +[s21; This text is almost identical copy of original [C docs/UnitTest`+`+.html] +file made by Noel Llopis, I (Peter `"Ped`" Helcmanovsky) made +only some U`+`+ related changes to it `- to make it more relevant +for U`+`+ users.&] +[s0; &] +[s3; U`+`+ wrapper&] +[s5; The U`+`+ version of UnitTest`+`+ consists of two packages:&] +[s5;i150;O0; [* UnitTest`+`+] is the actual unit testing library. This +is the package which you should add to your current project, +if you want to use unit testing.&] +[s5;i150;O0; [* UnitTestTest ]is the package containing tests of UnitTest`+`+. +This is standalone runnable package which was used to develop +the UnitTest`+`+ (and verify U`+`+ wrapper). Use this one to +test the main package works as expected, when you do custom changes +to main library or just read the source to get some inspiration +how the library can be used.&] +[s3; Using UnitTest`+`+&] +[s5; The U`+`+ version of UnitTest`+`+ comes with UnitTestTest package, +which is a full test suite using UnitTest`+`+. This is a great +place to learn techniques for testing. There is one sample .cpp +file: [C UnitTestTest/TestUnitTest`+`+.cpp]. It covers most of UnitTest`+`+`'s +features in an easy`-to`-grasp context, so start there if you +want a quick overview of typical usage.&] +[s22; Getting started&] +[s0; Create new package based on [C Core console project] (in an assembly +where bazaar package nest is defined). Add bazaar package UnitTest`+`+ +to it. Now adjust the cpp file to look like this:&] +[s0; &] +[s7; //some`_test.cpp&] +[s7; #include &] +[s7; #include &] +[s7; &] +[s7; TEST(FailSpectacularly)&] +[s7; `{&] +[s7; -|CHECK(false);&] +[s7; `}&] +[s7; &] +[s7; CONSOLE`_APP`_MAIN&] +[s7; `{&] +[s7; -|UPP`::SetExitCode( UnitTest`::RunAllTests() );&] +[s7; `}&] +[s21; [C UnitTest`+`+.h] is a facade header for UnitTest`+`+, so including +that should get you all features of the library. All classes +and free functions are placed in namespace [C UnitTest], so you +need to either qualify their full names (as with [C RunAllTests()] +in the example) or add a [C using namespace UnitTest;] statement +in your .cpp files. Note that any mention of UnitTest`+`+ functions +and classes in this document assume that the [C UnitTest] namespace +has been opened.&] +[s0; &] +[s0; Building this application and running it should produce the +following output (details may vary):&] +[s0; &] +[s7; .`\some`_test.cpp(5): error: Failure in FailSpectacularly: false&] +[s7; FAILED: 1 out of 1 tests failed (1 failures).&] +[s7; Test time: 0.00 seconds.&] +[s0; &] +[s0; UnitTest`+`+ attempts to report every failure in an IDE`-friendly +format, depending on platform (e.g. you can double`-click it +in Visual Studio`'s error list.) The exit code will be the number +of failed tests, so that a failed test run always returns a non`-zero +exit code.&] +[s22; Test macros&] +[s0; To add a test, simply put the following code in a .cpp file +of your choice:&] +[s0; &] +[s7; TEST(YourTestName)&] +[s7; `{&] +[s7; `}&] +[s0; &] +[s0; The [C TEST] macro contains enough machinery to turn this slightly +odd`-looking syntax into legal C`+`+, and automatically register +the test in a global list. This test list forms the basis of +what is executed by [C RunAllTests()].&] +[s0; &] +[s0; If you want to re`-use a set of test data for more than one +test, or provide setup/teardown for tests, you can use the [C TEST`_FIXTURE] +macro instead. The macro requires that you pass it a class name +that it will instantiate, so any setup and teardown code should +be in its constructor and destructor.&] +[s0; &] +[s7; struct SomeFixture&] +[s7; `{&] +[s7; -|SomeFixture() `{ /`* some setup `*/ `}&] +[s7; -|`~SomeFixture() `{ /`* some teardown `*/ `}&] +[s7; &] +[s7; -|int testData;&] +[s7; `};&] +[s7; &] +[s7; TEST`_FIXTURE(SomeFixture, YourTestName)&] +[s7; `{&] +[s7; -|int temp `= testData;&] +[s7; `}&] +[s0; &] +[s0; Note how members of the fixture are used as if they are a part +of the test, since the macro`-generated test class derives from +the provided fixture class.&] +[s22; Suite macros&] +[s0; Tests can be grouped into suites, using the [C SUITE] macro. A +suite serves as a namespace for test names, so that the same +test name can be used in two difference contexts.&] +[s0; &] +[s7; SUITE(YourSuiteName)&] +[s7; `{&] +[s7; -|TEST(YourTestName)&] +[s7; -|`{&] +[s7; -|`}&] +[s7; &] +[s7; -|TEST(YourOtherTestName)&] +[s7; -|`{&] +[s7; -|`}&] +[s7; `}&] +[s0; &] +[s0; This will place the tests into a C`+`+ namespace called [C YourSuiteName], +and make the suite name available to UnitTest`+`+. [C RunAllTests()] +can be called for a specific suite name, so you can use this +to build named groups of tests to be run together.&] +[s22; Simple check macros&] +[s0; In test cases, we want to check the results of our system under +test. UnitTest`+`+ provides a number of check macros that handle +comparison and proper failure reporting.&] +[s0; &] +[s0; The most basic variety is the boolean [C CHECK] macro:&] +[s0; &] +[s7; CHECK(false); // fails&] +[s0; &] +[s0; It will fail if the boolean expression evaluates to false.&] +[s0; &] +[s0; For equality checks, it`'s generally better to use [C CHECK`_EQUAL]:&] +[s0; &] +[s7; CHECK`_EQUAL(10, 20); // fails&] +[s7; CHECK`_EQUAL(`"foo`", `"bar`"); // fails&] +[s0; &] +[s0; Note how [C CHECK`_EQUAL] is overloaded for C strings, so you +don`'t have to resort to [C strcmp] or similar. There is no facility +for case`-insensitive comparison or string searches, so you may +have to drop down to a plain boolean [C CHECK] with help from the +CRT:&] +[s0; &] +[s7; CHECK(std`::strstr(`"zaza`", `"az`") !`= 0); // succeeds&] +[s0; &] +[s0; For floating`-point comparison, equality isn`'t necessarily +well`-defined, so you should prefer the [C CHECK`_CLOSE] macro:&] +[s0; &] +[s7; CHECK`_CLOSE(3.14, 3.1415, 0.01); // succeeds&] +[s0; &] +[s0; All of the macros are tailored to avoid unintended side`-effects, +for example:&] +[s0; &] +[s7; TEST(CheckMacrosHaveNoSideEffects)&] +[s7; `{&] +[s7; -|int i `= 4;&] +[s7; -|CHECK`_EQUAL(5, `+`+i); // succeeds&] +[s7; -|CHECK`_EQUAL(5, i); // succeeds&] +[s7; `}&] +[s0; &] +[s0; The check macros guarantee that the [C `+`+i] expression isn`'t +repeated internally, as demonstrated above.&] +[s22; Array check macros&] +[s0; There is a set of check macros for array comparison as well:&] +[s0; &] +[s7; const float oned`[2`] `= `{ 10, 20 `};&] +[s7; CHECK`_ARRAY`_EQUAL(oned, oned, 2); // succeeds&] +[s7; CHECK`_ARRAY`_CLOSE(oned, oned, 2, 0.00); // succeeds&] +[s7; &] +[s7; const float twod`[2`]`[3`] `= `{ `{0, 1, 2`}, `{2, 3, 4`} `};&] +[s7; CHECK`_ARRAY2D`_CLOSE(twod, twod, 2, 3, 0.00); // succeeds&] +[s0; &] +[s0; The array equal macro compares elements using [C operator`=`=], +so [C CHECK`_ARRAY`_EQUAL] won`'t work for an array of C strings, +for example.&] +[s0; &] +[s0; The array close macros are similar to the regular [C CHECK`_CLOSE] +macro, and are really only useful for scalar types, that can +be compared in terms of a difference between two array elements.&] +[s0; &] +[s0; Note that the one`-dimensional array macros work for [C std`::vector] +as well, as it can be indexed just as a C array.&] +[s22; Exception check macros&] +[s0; Finally, there`'s a [C CHECK`_THROW] macro, which asserts that +its enclosed expression throws the specified type:&] +[s0; &] +[s7; struct TestException `{`};&] +[s7; CHECK`_THROW(throw TestException(), TestException); // succeeds&] +[s0; &] +[s0; UnitTest`+`+ natively catches exceptions if your test code doesn`'t. +So if your code under test throws any exception UnitTest`+`+ +will fail the test and report either using the [C what()] method +for [C std`::exception] derivatives or just a plain message for +unknown exception types.&] +[s0; &] +[s0; Should your test or code raise an irrecoverable error (an Access +Violation on Win32, for example, or a signal on Linux), UnitTest`+`+ +will attempt to map them to an exception and fail the test, just +as for other unhandled exceptions.&] +[s22; Time constraints&] +[s0; UnitTest`+`+ can fail a test if it takes too long to complete, +using so`-called time constraints.&] +[s0; &] +[s0; They come in two flavors; local and global time constraints.&] +[s0; &] +[s0; Local time constraints are limited to the current scope, like +so:&] +[s0; &] +[s7; TEST(YourTimedTest)&] +[s7; `{&] +[s7; -|// Lengthy setup...&] +[s7; &] +[s7; -|`{&] +[s7; -|-|UNITTEST`_TIME`_CONSTRAINT(50);&] +[s7; &] +[s7; -|-|// Do time`-critical stuff&] +[s7; -|`}&] +[s7; &] +[s7; -|// Lengthy teardown...&] +[s7; `}&] +[s0; &] +[s0; The test will fail if the `"Do time`-critical stuff`" block +takes longer than 50 ms to complete. The time`-consuming setup +and teardown are not measured, since the time constraint is scope`-bound. +It`'s perfectly valid to have multiple local time constraints +in the same test, as long as there is only one per block.&] +[s0; &] +[s0; A global time constraint, on the other hand, requires that all +of the tests in a test run are faster than a specified amount +of time. This allows you, when you run a suite of tests, to ask +UnitTest`+`+ to fail it entirely if any test exceeds the global +constraint. The max time is passed as a parameter to an overload +of [C RunAllTests()].&] +[s0; &] +[s0; If you want to use a global time constraint, but have one test +that is notoriously slow, you can exempt it from inspection by +using the [C UNITTEST`_TIME`_CONSTRAINT`_EXEMPT] macro anywhere +inside the test body.&] +[s0; &] +[s7; TEST(NotoriouslySlowTest)&] +[s7; `{&] +[s7; -|UNITTEST`_TIME`_CONSTRAINT`_EXEMPT();&] +[s7; &] +[s7; -|// Oh boy, this is going to take a while&] +[s7; -|...&] +[s7; `}&] +[s22; Test runners&] +[s0; The [C RunAllTests()] function has an overload that lets you customize +the behavior of the runner, such as global time constraints, +custom reporters, which suite to run, etc.&] +[s0; &] +[s7; int RunAllTests(TestReporter`& reporter, TestList const`& list, +char const`* suiteName, int const maxTestTimeInMs);&] +[s0; &] +[s0; If you attempt to pass custom parameters to [C RunAllTests()], +note that the list parameter should have the value [C Test`::GetTestList()].&] +[s0; &] +[s0; The parameterless [C RunAllTests()] is a simple wrapper for this +one, with sensible defaults.&] +[s22; Example setup&] +[s0; How to create a new test project varies depending on your environment, +but here are some directions on common file structure and usage.&] +[s0; &] +[s0; The general idea is that you keep one Main.cpp file with the +entry`-point which calls RunAllTests().&] +[s0; &] +[s0; Then you can simply compile and link new .cpp files at will, +typically one per test suite.&] +[s0; &] +[s0; `+ ShaverTests/&] +[s0; `|&] +[s0; `+`- Main.cpp&] +[s0; `|&] +[s0; `+`- TestBrush.cpp &] +[s0; `+`- TestEngine.cpp&] +[s0; `+`- TestRazor.cpp &] +[s0; &] +[s0; Each of the Test`*.cpp files will contain one or more TEST macro +incantations with the associated test code. There are no source`-level +dependencies between Main.cpp and Test`*.cpp, as the TEST macro +handles the registration and setup necessary for RunAllTests() +to find all tests compiled into the same final executable.&] +[s0; &] +[s0; UnitTest`+`+ does not require this structure, even if this is +how the library itself does it. As long as your test project +contains one or more TESTs and calls RunAllTests() at one point +or another, it will be handled by UnitTest`+`+.&] +[s0; &] +[s0; It`'s common to make the generated executable start as a post`-build +step, so that merely building your test project will run the +tests as well. Since the exit code is the count of failures, +a failed test will generally break the build, as most build engines +will fail a build if any step returns a non`-zero exit code.] \ No newline at end of file