JUCE  v5.4.1-191-g0ab5e696f
JUCE API
Looking for a senior C++ dev?
I'm looking for work. Hire me!
juce::UnitTest Class Referenceabstract

This is a base class for classes that perform a unit test. More...

#include <juce_UnitTest.h>

Collaboration diagram for juce::UnitTest:

Public Member Functions

 UnitTest (const String &name, const String &category=String())
 Creates a test with the given name and optionally places it in a category. More...
 
virtual ~UnitTest ()
 Destructor. More...
 
void beginTest (const String &testName)
 Tells the system that a new subsection of tests is beginning. More...
 
void expect (bool testResult, const String &failureMessage=String())
 Checks that the result of a test is true, and logs this result. More...
 
template<class ValueType >
void expectEquals (ValueType actual, ValueType expected, String failureMessage=String())
 Compares a value to an expected value. More...
 
template<class ValueType >
void expectGreaterOrEqual (ValueType value, ValueType valueToCompareTo, String failureMessage=String())
 Checks whether a value is greater or equal to a comparison value. More...
 
template<class ValueType >
void expectGreaterThan (ValueType value, ValueType valueToCompareTo, String failureMessage=String())
 Checks whether a value is greater than a comparison value. More...
 
template<class ValueType >
void expectLessOrEqual (ValueType value, ValueType valueToCompareTo, String failureMessage=String())
 Checks whether a value is less or equal to a comparison value. More...
 
template<class ValueType >
void expectLessThan (ValueType value, ValueType valueToCompareTo, String failureMessage=String())
 Checks whether a value is less than a comparison value. More...
 
template<class ValueType >
void expectNotEquals (ValueType value, ValueType valueToCompareTo, String failureMessage=String())
 Checks whether a value is not equal to a comparison value. More...
 
template<class ValueType >
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 maximum value, prints out a message containing the actual and comparison values and the maximum allowed error. More...
 
const StringgetCategory () const noexcept
 Returns the category of the test. More...
 
const StringgetName () const noexcept
 Returns the name of the test. More...
 
Random getRandom () const
 Returns a shared RNG that all unit tests should use. More...
 
virtual void initialise ()
 You can optionally implement this method to set up your test. More...
 
void logMessage (const String &message)
 Writes a message to the test log. More...
 
void performTest (UnitTestRunner *runner)
 Runs the test, using the specified UnitTestRunner. More...
 
virtual void runTest ()=0
 Implement this method in your subclass to actually run your tests. More...
 
virtual void shutdown ()
 You can optionally implement this method to clear up after your test has been run. More...
 

Static Public Member Functions

static StringArray getAllCategories ()
 Returns a StringArray containing all of the categories of UnitTests that have been registered. More...
 
static Array< UnitTest * > & getAllTests ()
 Returns the set of all UnitTest objects that currently exist. More...
 
static Array< UnitTest * > getTestsInCategory (const String &category)
 Returns the set of UnitTests in a specified category. More...
 

Private Member Functions

template<class ValueType >
void expectResultAndPrint (ValueType value, ValueType valueToCompareTo, bool result, String compDescription, String failureMessage)
 

Private Attributes

const String category
 
const String name
 
UnitTestRunnerrunner = nullptr
 

Detailed Description

This is a base class for classes that perform a unit test.

To write a test using this class, your code should look something like this:

class MyTest : public UnitTest
{
public:
MyTest() : UnitTest ("Foobar testing") {}
void runTest() override
{
beginTest ("Part 1");
expect (myFoobar.doesSomething());
expect (myFoobar.doesSomethingElse());
beginTest ("Part 2");
expect (myOtherFoobar.doesSomething());
expect (myOtherFoobar.doesSomethingElse());
...etc..
}
};
// Creating a static instance will automatically add the instance to the array
// returned by UnitTest::getAllTests(), so the test will be included when you call
// UnitTestRunner::runAllTests()
static MyTest test;

To run a test, use the UnitTestRunner class.

See also
UnitTestRunner

{Core}

Constructor & Destructor Documentation

◆ UnitTest()

juce::UnitTest::UnitTest ( const String name,
const String category = String() 
)
explicit

Creates a test with the given name and optionally places it in a category.

◆ ~UnitTest()

virtual juce::UnitTest::~UnitTest ( )
virtual

Destructor.

Member Function Documentation

◆ beginTest()

void juce::UnitTest::beginTest ( const String testName)

Tells the system that a new subsection of tests is beginning.

This should be called from your runTest() method, and may be called as many times as you like, to demarcate different sets of tests.

◆ expect()

void juce::UnitTest::expect ( bool  testResult,
const String failureMessage = String() 
)

Checks that the result of a test is true, and logs this result.

In your runTest() method, you should call this method for each condition that you want to check, e.g.

void runTest()
{
beginTest ("basic tests");
expect (x + y == 2);
expect (getThing() == someThing);
...etc...
}

If testResult is true, a pass is logged; if it's false, a failure is logged. If the failure message is specified, it will be written to the log if the test fails.

◆ expectEquals()

template<class ValueType >
void juce::UnitTest::expectEquals ( ValueType  actual,
ValueType  expected,
String  failureMessage = String() 
)
inline

Compares a value to an expected value.

If they are not equal, prints out a message containing the expected and actual values.

◆ expectGreaterOrEqual()

template<class ValueType >
void juce::UnitTest::expectGreaterOrEqual ( ValueType  value,
ValueType  valueToCompareTo,
String  failureMessage = String() 
)
inline

Checks whether a value is greater or equal to a comparison value.

If this check fails, prints out a message containing the actual and comparison values.

◆ expectGreaterThan()

template<class ValueType >
void juce::UnitTest::expectGreaterThan ( ValueType  value,
ValueType  valueToCompareTo,
String  failureMessage = String() 
)
inline

Checks whether a value is greater than a comparison value.

If this check fails, prints out a message containing the actual and comparison values.

◆ expectLessOrEqual()

template<class ValueType >
void juce::UnitTest::expectLessOrEqual ( ValueType  value,
ValueType  valueToCompareTo,
String  failureMessage = String() 
)
inline

Checks whether a value is less or equal to a comparison value.

If this check fails, prints out a message containing the actual and comparison values.

◆ expectLessThan()

template<class ValueType >
void juce::UnitTest::expectLessThan ( ValueType  value,
ValueType  valueToCompareTo,
String  failureMessage = String() 
)
inline

Checks whether a value is less than a comparison value.

If this check fails, prints out a message containing the actual and comparison values.

◆ expectNotEquals()

template<class ValueType >
void juce::UnitTest::expectNotEquals ( ValueType  value,
ValueType  valueToCompareTo,
String  failureMessage = String() 
)
inline

Checks whether a value is not equal to a comparison value.

If this check fails, prints out a message containing the actual and comparison values.

◆ expectResultAndPrint()

template<class ValueType >
void juce::UnitTest::expectResultAndPrint ( ValueType  value,
ValueType  valueToCompareTo,
bool  result,
String  compDescription,
String  failureMessage 
)
inlineprivate

◆ expectWithinAbsoluteError()

template<class ValueType >
void juce::UnitTest::expectWithinAbsoluteError ( ValueType  actual,
ValueType  expected,
ValueType  maxAbsoluteError,
String  failureMessage = String() 
)
inline

Computes the difference between a value and a comparison value, and if it is larger than a specified maximum value, prints out a message containing the actual and comparison values and the maximum allowed error.

◆ getAllCategories()

static StringArray juce::UnitTest::getAllCategories ( )
static

Returns a StringArray containing all of the categories of UnitTests that have been registered.

◆ getAllTests()

static Array<UnitTest*>& juce::UnitTest::getAllTests ( )
static

Returns the set of all UnitTest objects that currently exist.

◆ getCategory()

const String& juce::UnitTest::getCategory ( ) const
inlinenoexcept

Returns the category of the test.

◆ getName()

const String& juce::UnitTest::getName ( ) const
inlinenoexcept

Returns the name of the test.

◆ getRandom()

Random juce::UnitTest::getRandom ( ) const

Returns a shared RNG that all unit tests should use.

If a test needs random numbers, it's important that when an error is found, the exact circumstances can be re-created in order to re-test the problem, by repeating the test with the same random seed value. To make this possible, the UnitTestRunner class creates a master seed value for the run, writes this number to the log, and then this method returns a Random object based on that seed. All tests should only use this method to create any Random objects that they need.

Note that this method will return an identical object each time it's called for a given run, so if you need several different Random objects, the best way to do that is to call Random::combineSeed() on the result to permute it with a constant value.

◆ getTestsInCategory()

static Array<UnitTest*> juce::UnitTest::getTestsInCategory ( const String category)
static

Returns the set of UnitTests in a specified category.

◆ initialise()

virtual void juce::UnitTest::initialise ( )
virtual

You can optionally implement this method to set up your test.

This method will be called before runTest().

◆ logMessage()

void juce::UnitTest::logMessage ( const String message)

Writes a message to the test log.

This can only be called from within your runTest() method.

◆ performTest()

void juce::UnitTest::performTest ( UnitTestRunner runner)

Runs the test, using the specified UnitTestRunner.

You shouldn't need to call this method directly - use UnitTestRunner::runTests() instead.

◆ runTest()

virtual void juce::UnitTest::runTest ( )
pure virtual

Implement this method in your subclass to actually run your tests.

The content of your implementation should call beginTest() and expect() to perform the tests.

◆ shutdown()

virtual void juce::UnitTest::shutdown ( )
virtual

You can optionally implement this method to clear up after your test has been run.

This method will be called after runTest() has returned.

Member Data Documentation

◆ category

const String juce::UnitTest::category
private

◆ name

const String juce::UnitTest::name
private

◆ runner

UnitTestRunner* juce::UnitTest::runner = nullptr
private

The documentation for this class was generated from the following file: