juce/source/src/utilities/juce_UnitTest.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_UNITTEST_JUCEHEADER__
  27 #define __JUCE_UNITTEST_JUCEHEADER__
  28
  29 #include "../text/juce_StringArray.h"
  30 #include "../containers/juce_OwnedArray.h"
  31 class UnitTestRunner;
  32
  33
  34 //==============================================================================
  35 /**
  36     This is a base class for classes that perform a unit test.
  37
  38     To write a test using this class, your code should look something like this:
  39
  40     @code
  41     class MyTest  : public UnitTest
  42     {
  43     public:
  44         MyTest()  : UnitTest ("Foobar testing") {}
  45
  46         void runTest()
  47         {
  48             beginTest ("Part 1");
  49
  50             expect (myFoobar.doesSomething());
  51             expect (myFoobar.doesSomethingElse());
  52
  53             beginTest ("Part 2");
  54
  55             expect (myOtherFoobar.doesSomething());
  56             expect (myOtherFoobar.doesSomethingElse());
  57
  58             ...etc..
  59         }
  60     };
  61
  62     // Creating a static instance will automatically add the instance to the array
  63     // returned by UnitTest::getAllTests(), so the test will be included when you call
  64     // UnitTestRunner::runAllTests()
  65     static MyTest test;
  66     @endcode
  67
  68     To run a test, use the UnitTestRunner class.
  69
  70     @see UnitTestRunner
  71 */
  72 class JUCE_API  UnitTest
  73 {
  74 public:
  75     //==============================================================================
  76     /** Creates a test with the given name. */
  77     explicit UnitTest (const String& name);
  78
  79     /** Destructor. */
  80     virtual ~UnitTest();
  81
  82     /** Returns the name of the test. */
  83     const String& getName() const noexcept       { return name; }
  84
  85     /** Runs the test, using the specified UnitTestRunner.
  86         You shouldn't need to call this method directly - use
  87         UnitTestRunner::runTests() instead.
  88     */
  89     void performTest (UnitTestRunner* runner);
  90
  91     /** Returns the set of all UnitTest objects that currently exist. */
  92     static Array<UnitTest*>& getAllTests();
  93
  94     //==============================================================================
  95     /** You can optionally implement this method to set up your test.
  96         This method will be called before runTest().
  97     */
  98     virtual void initialise();
  99
 100     /** You can optionally implement this method to clear up after your test has been run.
 101         This method will be called after runTest() has returned.
 102     */
 103     virtual void shutdown();
 104
 105     /** Implement this method in your subclass to actually run your tests.
 106
 107         The content of your implementation should call beginTest() and expect()
 108         to perform the tests.
 109     */
 110     virtual void runTest() = 0;
 111
 112     //==============================================================================
 113     /** Tells the system that a new subsection of tests is beginning.
 114         This should be called from your runTest() method, and may be called
 115         as many times as you like, to demarcate different sets of tests.
 116     */
 117     void beginTest (const String& testName);
 118
 119     //==============================================================================
 120     /** Checks that the result of a test is true, and logs this result.
 121
 122         In your runTest() method, you should call this method for each condition that
 123         you want to check, e.g.
 124
 125         @code
 126         void runTest()
 127         {
 128             beginTest ("basic tests");
 129             expect (x + y == 2);
 130             expect (getThing() == someThing);
 131             ...etc...
 132         }
 133         @endcode
 134
 135         If testResult is true, a pass is logged; if it's false, a failure is logged.
 136         If the failure message is specified, it will be written to the log if the test fails.
 137     */
 138     void expect (bool testResult, const String& failureMessage = String::empty);
 139
 140     /** Compares two values, and if they don't match, prints out a message containing the
 141         expected and actual result values.
 142     */
 143     template <class ValueType>
 144     void expectEquals (ValueType actual, ValueType expected, String failureMessage = String::empty)
 145     {
 146         const bool result = (actual == expected);
 147
 148         if (! result)
 149         {
 150             if (failureMessage.isNotEmpty())
 151                 failureMessage << " -- ";
 152
 153             failureMessage << "Expected value: " << expected << ", Actual value: " << actual;
 154         }
 155
 156         expect (result, failureMessage);
 157     }
 158
 159     //==============================================================================
 160     /** Writes a message to the test log.
 161         This can only be called from within your runTest() method.
 162     */
 163     void logMessage (const String& message);
 164
 165 private:
 166     //==============================================================================
 167     const String name;
 168     UnitTestRunner* runner;
 169
 170     JUCE_DECLARE_NON_COPYABLE (UnitTest);
 171 };
 172
 173
 174 //==============================================================================
 175 /**
 176     Runs a set of unit tests.
 177
 178     You can instantiate one of these objects and use it to invoke tests on a set of
 179     UnitTest objects.
 180
 181     By using a subclass of UnitTestRunner, you can intercept logging messages and
 182     perform custom behaviour when each test completes.
 183
 184     @see UnitTest
 185 */
 186 class JUCE_API  UnitTestRunner
 187 {
 188 public:
 189     //==============================================================================
 190     /** */
 191     UnitTestRunner();
 192
 193     /** Destructor. */
 194     virtual ~UnitTestRunner();
 195
 196     /** Runs a set of tests.
 197
 198         The tests are performed in order, and the results are logged. To run all the
 199         registered UnitTest objects that exist, use runAllTests().
 200     */
 201     void runTests (const Array<UnitTest*>& tests, bool assertOnFailure);
 202
 203     /** Runs all the UnitTest objects that currently exist.
 204         This calls runTests() for all the objects listed in UnitTest::getAllTests().
 205     */
 206     void runAllTests (bool assertOnFailure);
 207
 208     //==============================================================================
 209     /** Contains the results of a test.
 210
 211         One of these objects is instantiated each time UnitTest::beginTest() is called, and
 212         it contains details of the number of subsequent UnitTest::expect() calls that are
 213         made.
 214     */
 215     struct TestResult
 216     {
 217         /** The main name of this test (i.e. the name of the UnitTest object being run). */
 218         String unitTestName;
 219         /** The name of the current subcategory (i.e. the name that was set when UnitTest::beginTest() was called). */
 220         String subcategoryName;
 221
 222         /** The number of UnitTest::expect() calls that succeeded. */
 223         int passes;
 224         /** The number of UnitTest::expect() calls that failed. */
 225         int failures;
 226
 227         /** A list of messages describing the failed tests. */
 228         StringArray messages;
 229     };
 230
 231     /** Returns the number of TestResult objects that have been performed.
 232         @see getResult
 233     */
 234     int getNumResults() const noexcept;
 235
 236     /** Returns one of the TestResult objects that describes a test that has been run.
 237         @see getNumResults
 238     */
 239     const TestResult* getResult (int index) const noexcept;
 240
 241 protected:
 242     /** Called when the list of results changes.
 243         You can override this to perform some sort of behaviour when results are added.
 244     */
 245     virtual void resultsUpdated();
 246
 247     /** Logs a message about the current test progress.
 248         By default this just writes the message to the Logger class, but you could override
 249         this to do something else with the data.
 250     */
 251     virtual void logMessage (const String& message);
 252
 253 private:
 254     //==============================================================================
 255     friend class UnitTest;
 256
 257     UnitTest* currentTest;
 258     String currentSubCategory;
 259     OwnedArray <TestResult, CriticalSection> results;
 260     bool assertOnFailure;
 261
 262     void beginNewTest (UnitTest* test, const String& subCategory);
 263     void endTest();
 264
 265     void addPass();
 266     void addFail (const String& failureMessage);
 267
 268     JUCE_DECLARE_NON_COPYABLE (UnitTestRunner);
 269 };
 270
 271
 272 #endif   // __JUCE_UNITTEST_JUCEHEADER__