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 
27 namespace juce
28 {
29 
30 class 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 {
75 public:
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>
155  void expectEquals (ValueType actual, ValueType expected, String failureMessage = String())
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>
165  void expectNotEquals (ValueType value, ValueType valueToCompareTo, String failureMessage = String())
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>
175  void expectGreaterThan (ValueType value, ValueType valueToCompareTo, String failureMessage = String())
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>
185  void expectLessThan (ValueType value, ValueType valueToCompareTo, String failureMessage = String())
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>
195  void expectGreaterOrEqual (ValueType value, ValueType valueToCompareTo, String failureMessage = String())
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>
205  void expectLessOrEqual (ValueType value, ValueType valueToCompareTo, String failureMessage = String())
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>
216  void expectWithinAbsoluteError (ValueType actual, ValueType expected, ValueType maxAbsoluteError, String failureMessage = String())
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 
287 private:
288  //==============================================================================
289  template <class ValueType>
290  void expectResultAndPrint (ValueType value, ValueType valueToCompareTo, bool result,
291  String compDescription, String failureMessage)
292  {
293  if (! result)
294  {
295  if (failureMessage.isNotEmpty())
296  failureMessage << " -- ";
297 
298  failureMessage << "Expected value" << (compDescription.isEmpty() ? "" : " ")
299  << compDescription << ": " << valueToCompareTo
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 {
330 public:
331  //==============================================================================
332  /** */
333  UnitTestRunner();
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  */
381  struct TestResult
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. */
389  int passes;
390  /** The number of UnitTest::expect() calls that failed. */
391  int failures;
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 
407 protected:
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 
424 private:
425  //==============================================================================
426  friend class UnitTest;
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 /** @}*/
juce::StringArray
A special array for holding a list of strings.
Definition: juce_StringArray.h:38
juce::UnitTest::expectLessOrEqual
void expectLessOrEqual(ValueType value, ValueType valueToCompareTo, String failureMessage=String())
Checks whether a value is less or equal to a comparison value.
Definition: juce_UnitTest.h:205
juce::OwnedArray
An array designed for holding objects.
Definition: juce_OwnedArray.h:54
juce::UnitTestRunner::TestResult::passes
int passes
The number of UnitTest::expect() calls that succeeded.
Definition: juce_UnitTest.h:389
juce::Array
Holds a resizable array of primitive or copy-by-value objects.
Definition: juce_Array.h:59
JUCE_API
#define JUCE_API
This macro is added to all JUCE public class declarations.
Definition: juce_StandardHeader.h:143
juce::UnitTestRunner::TestResult
Contains the results of a test.
Definition: juce_UnitTest.h:381
juce::UnitTest::expectNotEquals
void expectNotEquals(ValueType value, ValueType valueToCompareTo, String failureMessage=String())
Checks whether a value is not equal to a comparison value.
Definition: juce_UnitTest.h:165
juce::UnitTest::expectGreaterOrEqual
void expectGreaterOrEqual(ValueType value, ValueType valueToCompareTo, String failureMessage=String())
Checks whether a value is greater or equal to a comparison value.
Definition: juce_UnitTest.h:195
juce::Random
A random number generator.
Definition: juce_Random.h:38
juce::UnitTestRunner::TestResult::failures
int failures
The number of UnitTest::expect() calls that failed.
Definition: juce_UnitTest.h:391
juce::UnitTest::expectWithinAbsoluteError
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 ...
Definition: juce_UnitTest.h:216
juce::UnitTest::expectGreaterThan
void expectGreaterThan(ValueType value, ValueType valueToCompareTo, String failureMessage=String())
Checks whether a value is greater than a comparison value.
Definition: juce_UnitTest.h:175
juce::UnitTestRunner::TestResult::messages
StringArray messages
A list of messages describing the failed tests.
Definition: juce_UnitTest.h:394
juce::UnitTest::getName
const String & getName() const noexcept
Returns the name of the test.
Definition: juce_UnitTest.h:84
juce::UnitTest::getCategory
const String & getCategory() const noexcept
Returns the category of the test.
Definition: juce_UnitTest.h:87
juce::String::isEmpty
bool isEmpty() const noexcept
Returns true if the string contains no characters.
Definition: juce_String.h:300
juce::UnitTestRunner::TestResult::unitTestName
String unitTestName
The main name of this test (i.e.
Definition: juce_UnitTest.h:384
juce::UnitTest::expectEquals
void expectEquals(ValueType actual, ValueType expected, String failureMessage=String())
Compares a value to an expected value.
Definition: juce_UnitTest.h:155
juce::UnitTest
This is a base class for classes that perform a unit test.
Definition: juce_UnitTest.h:73
juce::String::isNotEmpty
bool isNotEmpty() const noexcept
Returns true if the string contains at least one character.
Definition: juce_String.h:306
juce::String
The JUCE String class!
Definition: juce_String.h:42
juce::CriticalSection
A re-entrant mutex.
Definition: juce_CriticalSection.h:46
juce::UnitTestRunner
Runs a set of unit tests.
Definition: juce_UnitTest.h:328
juce::UnitTestRunner::TestResult::subcategoryName
String subcategoryName
The name of the current subcategory (i.e.
Definition: juce_UnitTest.h:386
juce::UnitTest::expectLessThan
void expectLessThan(ValueType value, ValueType valueToCompareTo, String failureMessage=String())
Checks whether a value is less than a comparison value.
Definition: juce_UnitTest.h:185