OpenShot Library | libopenshot-audio 0.2.0
juce_UnitTest.h
1
2/** @weakgroup juce_core-unit_tests
3 * @{
4 */
5/*
6 ==============================================================================
7
8 This file is part of the JUCE library.
9 Copyright (c) 2017 - ROLI Ltd.
10
11 JUCE is an open source library subject to commercial or open-source
12 licensing.
13
14 The code included in this file is provided under the terms of the ISC license
15 http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16 To use, copy, modify, and/or distribute this software for any purpose with or
17 without fee is hereby granted provided that the above copyright notice and
18 this permission notice appear in all copies.
19
20 JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21 EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22 DISCLAIMED.
23
24 ==============================================================================
25*/
26
27namespace juce
28{
29
30class UnitTestRunner;
31
32
33//==============================================================================
34/**
35 This is a base class for classes that perform a unit test.
36
37 To write a test using this class, your code should look something like this:
38
39 @code
40 class MyTest : public UnitTest
41 {
42 public:
43 MyTest() : UnitTest ("Foobar testing") {}
44
45 void runTest() override
46 {
47 beginTest ("Part 1");
48
49 expect (myFoobar.doesSomething());
50 expect (myFoobar.doesSomethingElse());
51
52 beginTest ("Part 2");
53
54 expect (myOtherFoobar.doesSomething());
55 expect (myOtherFoobar.doesSomethingElse());
56
57 ...etc..
58 }
59 };
60
61 // Creating a static instance will automatically add the instance to the array
62 // returned by UnitTest::getAllTests(), so the test will be included when you call
63 // UnitTestRunner::runAllTests()
64 static MyTest test;
65 @endcode
66
67 To run a test, use the UnitTestRunner class.
68
69 @see UnitTestRunner
70
71 @tags{Core}
72*/
74{
75public:
76 //==============================================================================
77 /** Creates a test with the given name and optionally places it in a category. */
78 explicit UnitTest (const String& name, const String& category = String());
79
80 /** Destructor. */
81 virtual ~UnitTest();
82
83 /** Returns the name of the test. */
84 const String& getName() const noexcept { return name; }
85
86 /** Returns the category of the test. */
87 const String& getCategory() const noexcept { return category; }
88
89 /** Runs the test, using the specified UnitTestRunner.
90 You shouldn't need to call this method directly - use
91 UnitTestRunner::runTests() instead.
92 */
93 void performTest (UnitTestRunner* runner);
94
95 /** Returns the set of all UnitTest objects that currently exist. */
96 static Array<UnitTest*>& getAllTests();
97
98 /** Returns the set of UnitTests in a specified category. */
99 static Array<UnitTest*> getTestsInCategory (const String& category);
100
101 /** Returns a StringArray containing all of the categories of UnitTests that have been registered. */
102 static StringArray getAllCategories();
103
104 //==============================================================================
105 /** You can optionally implement this method to set up your test.
106 This method will be called before runTest().
107 */
108 virtual void initialise();
109
110 /** You can optionally implement this method to clear up after your test has been run.
111 This method will be called after runTest() has returned.
112 */
113 virtual void shutdown();
114
115 /** Implement this method in your subclass to actually run your tests.
116
117 The content of your implementation should call beginTest() and expect()
118 to perform the tests.
119 */
120 virtual void runTest() = 0;
121
122 //==============================================================================
123 /** Tells the system that a new subsection of tests is beginning.
124 This should be called from your runTest() method, and may be called
125 as many times as you like, to demarcate different sets of tests.
126 */
127 void beginTest (const String& testName);
128
129 //==============================================================================
130 /** Checks that the result of a test is true, and logs this result.
131
132 In your runTest() method, you should call this method for each condition that
133 you want to check, e.g.
134
135 @code
136 void runTest()
137 {
138 beginTest ("basic tests");
139 expect (x + y == 2);
140 expect (getThing() == someThing);
141 ...etc...
142 }
143 @endcode
144
145 If testResult is true, a pass is logged; if it's false, a failure is logged.
146 If the failure message is specified, it will be written to the log if the test fails.
147 */
148 void expect (bool testResult, const String& failureMessage = String());
149
150 //==============================================================================
151 /** Compares a value to an expected value.
152 If they are not equal, prints out a message containing the expected and actual values.
153 */
154 template <class ValueType>
156 {
157 bool result = actual == expected;
158 expectResultAndPrint (actual, expected, result, "", failureMessage);
159 }
160
161 /** Checks whether a value is not equal to a comparison value.
162 If this check fails, prints out a message containing the actual and comparison values.
163 */
164 template <class ValueType>
166 {
167 bool result = value != valueToCompareTo;
168 expectResultAndPrint (value, valueToCompareTo, result, "unequal to", failureMessage);
169 }
170
171 /** Checks whether a value is greater than a comparison value.
172 If this check fails, prints out a message containing the actual and comparison values.
173 */
174 template <class ValueType>
176 {
177 bool result = value > valueToCompareTo;
178 expectResultAndPrint (value, valueToCompareTo, result, "greater than", failureMessage);
179 }
180
181 /** Checks whether a value is less than a comparison value.
182 If this check fails, prints out a message containing the actual and comparison values.
183 */
184 template <class ValueType>
186 {
187 bool result = value < valueToCompareTo;
188 expectResultAndPrint (value, valueToCompareTo, result, "less than", failureMessage);
189 }
190
191 /** Checks whether a value is greater or equal to a comparison value.
192 If this check fails, prints out a message containing the actual and comparison values.
193 */
194 template <class ValueType>
196 {
197 bool result = value >= valueToCompareTo;
198 expectResultAndPrint (value, valueToCompareTo, result, "greater or equal to", failureMessage);
199 }
200
201 /** Checks whether a value is less or equal to a comparison value.
202 If this check fails, prints out a message containing the actual and comparison values.
203 */
204 template <class ValueType>
206 {
207 bool result = value <= valueToCompareTo;
208 expectResultAndPrint (value, valueToCompareTo, result, "less or equal to", failureMessage);
209 }
210
211 /** Computes the difference between a value and a comparison value, and if it is larger than a
212 specified maximum value, prints out a message containing the actual and comparison values
213 and the maximum allowed error.
214 */
215 template <class ValueType>
217 {
218 const ValueType diff = std::abs (actual - expected);
219 const bool result = diff <= maxAbsoluteError;
220
221 expectResultAndPrint (actual, expected, result, " within " + String (maxAbsoluteError) + " of" , failureMessage);
222 }
223
224 //==============================================================================
225 /** Checks that the result of an expression does not throw an exception. */
226 #define expectDoesNotThrow(expr) \
227 try \
228 { \
229 (expr); \
230 expect (true); \
231 } \
232 catch (...) \
233 { \
234 expect (false, "Expected: does not throw an exception, Actual: throws."); \
235 }
236
237 /** Checks that the result of an expression throws an exception. */
238 #define expectThrows(expr) \
239 try \
240 { \
241 (expr); \
242 expect (false, "Expected: throws an exception, Actual: does not throw."); \
243 } \
244 catch (...) \
245 { \
246 expect (true); \
247 }
248
249 /** Checks that the result of an expression throws an exception of a certain type. */
250 #define expectThrowsType(expr, type) \
251 try \
252 { \
253 (expr); \
254 expect (false, "Expected: throws an exception of type " #type ", Actual: does not throw."); \
255 } \
256 catch (type&) \
257 { \
258 expect (true); \
259 } \
260 catch (...) \
261 { \
262 expect (false, "Expected: throws an exception of type " #type ", Actual: throws another type."); \
263 }
264
265 //==============================================================================
266 /** Writes a message to the test log.
267 This can only be called from within your runTest() method.
268 */
269 void logMessage (const String& message);
270
271 /** Returns a shared RNG that all unit tests should use.
272 If a test needs random numbers, it's important that when an error is found, the
273 exact circumstances can be re-created in order to re-test the problem, by
274 repeating the test with the same random seed value.
275 To make this possible, the UnitTestRunner class creates a master seed value
276 for the run, writes this number to the log, and then this method returns a
277 Random object based on that seed. All tests should only use this method to
278 create any Random objects that they need.
279
280 Note that this method will return an identical object each time it's called
281 for a given run, so if you need several different Random objects, the best
282 way to do that is to call Random::combineSeed() on the result to permute it
283 with a constant value.
284 */
285 Random getRandom() const;
286
287private:
288 //==============================================================================
289 template <class ValueType>
290 void expectResultAndPrint (ValueType value, ValueType valueToCompareTo, bool result,
292 {
293 if (! result)
294 {
295 if (failureMessage.isNotEmpty())
296 failureMessage << " -- ";
297
298 failureMessage << "Expected value" << (compDescription.isEmpty() ? "" : " ")
300 << ", Actual value: " << value;
301 }
302
303 expect (result, failureMessage);
304 }
305
306 //==============================================================================
307 const String name, category;
308 UnitTestRunner* runner = nullptr;
309
310 JUCE_DECLARE_NON_COPYABLE (UnitTest)
311};
312
313
314//==============================================================================
315/**
316 Runs a set of unit tests.
317
318 You can instantiate one of these objects and use it to invoke tests on a set of
319 UnitTest objects.
320
321 By using a subclass of UnitTestRunner, you can intercept logging messages and
322 perform custom behaviour when each test completes.
323
324 @see UnitTest
325
326 @tags{Core}
327*/
329{
330public:
331 //==============================================================================
332 /** */
334
335 /** Destructor. */
336 virtual ~UnitTestRunner();
337
338 /** Runs a set of tests.
339
340 The tests are performed in order, and the results are logged. To run all the
341 registered UnitTest objects that exist, use runAllTests().
342
343 If you want to run the tests with a predetermined seed, you can pass that into
344 the randomSeed argument, or pass 0 to have a randomly-generated seed chosen.
345 */
346 void runTests (const Array<UnitTest*>& tests, int64 randomSeed = 0);
347
348 /** Runs all the UnitTest objects that currently exist.
349 This calls runTests() for all the objects listed in UnitTest::getAllTests().
350
351 If you want to run the tests with a predetermined seed, you can pass that into
352 the randomSeed argument, or pass 0 to have a randomly-generated seed chosen.
353 */
354 void runAllTests (int64 randomSeed = 0);
355
356 /** Runs all the UnitTest objects within a specified category.
357 This calls runTests() for all the objects listed in UnitTest::getTestsInCategory().
358
359 If you want to run the tests with a predetermined seed, you can pass that into
360 the randomSeed argument, or pass 0 to have a randomly-generated seed chosen.
361 */
362 void runTestsInCategory (const String& category, int64 randomSeed = 0);
363
364 /** Sets a flag to indicate whether an assertion should be triggered if a test fails.
365 This is true by default.
366 */
367 void setAssertOnFailure (bool shouldAssert) noexcept;
368
369 /** Sets a flag to indicate whether successful tests should be logged.
370 By default, this is set to false, so that only failures will be displayed in the log.
371 */
372 void setPassesAreLogged (bool shouldDisplayPasses) noexcept;
373
374 //==============================================================================
375 /** Contains the results of a test.
376
377 One of these objects is instantiated each time UnitTest::beginTest() is called, and
378 it contains details of the number of subsequent UnitTest::expect() calls that are
379 made.
380 */
382 {
383 /** The main name of this test (i.e. the name of the UnitTest object being run). */
385 /** The name of the current subcategory (i.e. the name that was set when UnitTest::beginTest() was called). */
387
388 /** The number of UnitTest::expect() calls that succeeded. */
390 /** The number of UnitTest::expect() calls that failed. */
392
393 /** A list of messages describing the failed tests. */
395 };
396
397 /** Returns the number of TestResult objects that have been performed.
398 @see getResult
399 */
400 int getNumResults() const noexcept;
401
402 /** Returns one of the TestResult objects that describes a test that has been run.
403 @see getNumResults
404 */
405 const TestResult* getResult (int index) const noexcept;
406
408 /** Called when the list of results changes.
409 You can override this to perform some sort of behaviour when results are added.
410 */
411 virtual void resultsUpdated();
412
413 /** Logs a message about the current test progress.
414 By default this just writes the message to the Logger class, but you could override
415 this to do something else with the data.
416 */
417 virtual void logMessage (const String& message);
418
419 /** This can be overridden to let the runner know that it should abort the tests
420 as soon as possible, e.g. because the thread needs to stop.
421 */
422 virtual bool shouldAbortTests();
423
424private:
425 //==============================================================================
427
428 UnitTest* currentTest = nullptr;
429 String currentSubCategory;
431 bool assertOnFailure = true, logPasses = false;
432 Random randomForTest;
433
434 void beginNewTest (UnitTest* test, const String& subCategory);
435 void endTest();
436
437 void addPass();
438 void addFail (const String& failureMessage);
439
440 JUCE_DECLARE_NON_COPYABLE (UnitTestRunner)
441};
442
443} // namespace juce
444
445/** @}*/
Holds a resizable array of primitive or copy-by-value objects.
Definition juce_Array.h:60
bool isEmpty() const noexcept
Returns true if the array is empty, false otherwise.
Definition juce_Array.h:226
An array designed for holding objects.
A random number generator.
Definition juce_Random.h:39
A special array for holding a list of strings.
The JUCE String class!
Definition juce_String.h:43
Runs a set of unit tests.
This is a base class for classes that perform a unit test.
const String & getName() const noexcept
Returns the name of the test.
const String & getCategory() const noexcept
Returns the category of the test.
void expectEquals(ValueType actual, ValueType expected, String failureMessage=String())
Compares a value to an expected value.
void expectGreaterThan(ValueType value, ValueType valueToCompareTo, String failureMessage=String())
Checks whether a value is greater than a comparison value.
void expectWithinAbsoluteError(ValueType actual, ValueType expected, ValueType maxAbsoluteError, String failureMessage=String())
Computes the difference between a value and a comparison value, and if it is larger than a specified ...
virtual void runTest()=0
Implement this method in your subclass to actually run your tests.
void expectLessThan(ValueType value, ValueType valueToCompareTo, String failureMessage=String())
Checks whether a value is less than a comparison value.
void expectLessOrEqual(ValueType value, ValueType valueToCompareTo, String failureMessage=String())
Checks whether a value is less or equal to a comparison value.
void expectNotEquals(ValueType value, ValueType valueToCompareTo, String failureMessage=String())
Checks whether a value is not equal to a comparison value.
void expectGreaterOrEqual(ValueType value, ValueType valueToCompareTo, String failureMessage=String())
Checks whether a value is greater or equal to a comparison value.
#define JUCE_API
This macro is added to all JUCE public class declarations.
int failures
The number of UnitTest::expect() calls that failed.
StringArray messages
A list of messages describing the failed tests.
String unitTestName
The main name of this test (i.e.
String subcategoryName
The name of the current subcategory (i.e.
int passes
The number of UnitTest::expect() calls that succeeded.
Contains the results of a test.