juce_UnitTest.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   The code included in this file is provided under the terms of the ISC license
   http://www.isc.org/downloads/software-support-policy/isc-license. Permission
   To use, copy, modify, and/or distribute this software for any purpose with or
   without fee is hereby granted provided that the above copyright notice and
   this permission notice appear in all copies.
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
namespace juce
{
 
class UnitTestRunner;
 
 
//==============================================================================
class JUCE_API  UnitTest
{
public:
    //==============================================================================
    explicit UnitTest (const String& name, const String& category = String());

    virtual ~UnitTest();

    const String& getName() const noexcept       { return name; }

    const String& getCategory() const noexcept   { return category; }

    void performTest (UnitTestRunner* runner);

    static Array<UnitTest*>& getAllTests();

    static Array<UnitTest*> getTestsInCategory (const String& category);

    static StringArray getAllCategories();
 
    //==============================================================================
    virtual void initialise();

    virtual void shutdown();

    virtual void runTest() = 0;
 
    //==============================================================================
    void beginTest (const String& testName);
 
    //==============================================================================
    void expect (bool testResult, const String& failureMessage = String());
 
    //==============================================================================
    template <class ValueType>
    void expectEquals (ValueType actual, ValueType expected, String failureMessage = String())
    {
        bool result = actual == expected;
        expectResultAndPrint (actual, expected, result, "", failureMessage);
    }

    template <class ValueType>
    void expectNotEquals (ValueType value, ValueType valueToCompareTo, String failureMessage = String())
    {
        bool result = value != valueToCompareTo;
        expectResultAndPrint (value, valueToCompareTo, result, "unequal to", failureMessage);
    }

    template <class ValueType>
    void expectGreaterThan (ValueType value, ValueType valueToCompareTo, String failureMessage = String())
    {
        bool result = value > valueToCompareTo;
        expectResultAndPrint (value, valueToCompareTo, result, "greater than", failureMessage);
    }

    template <class ValueType>
    void expectLessThan (ValueType value, ValueType valueToCompareTo, String failureMessage = String())
    {
        bool result = value < valueToCompareTo;
        expectResultAndPrint (value, valueToCompareTo, result, "less than", failureMessage);
    }

    template <class ValueType>
    void expectGreaterOrEqual (ValueType value, ValueType valueToCompareTo, String failureMessage = String())
    {
        bool result = value >= valueToCompareTo;
        expectResultAndPrint (value, valueToCompareTo, result, "greater or equal to", failureMessage);
    }

    template <class ValueType>
    void expectLessOrEqual (ValueType value, ValueType valueToCompareTo, String failureMessage = String())
    {
        bool result = value <= valueToCompareTo;
        expectResultAndPrint (value, valueToCompareTo, result, "less or equal to", failureMessage);
    }

    template <class ValueType>
    void expectWithinAbsoluteError (ValueType actual, ValueType expected, ValueType maxAbsoluteError, String failureMessage = String())
    {
        const ValueType diff = std::abs (actual - expected);
        const bool result = diff <= maxAbsoluteError;
 
        expectResultAndPrint (actual, expected, result, " within " + String (maxAbsoluteError) + " of" , failureMessage);
    }
 
    //==============================================================================
    #define expectDoesNotThrow(expr)         \
        try                                  \
        {                                    \
            (expr);                          \
            expect (true);                   \
        }                                    \
        catch (...)                          \
        {                                    \
            expect (false, "Expected: does not throw an exception, Actual: throws."); \
        }

    #define expectThrows(expr)               \
        try                                  \
        {                                    \
            (expr);                          \
            expect (false, "Expected: throws an exception, Actual: does not throw."); \
        }                                    \
        catch (...)                          \
        {                                    \
            expect (true);                   \
        }

    #define expectThrowsType(expr, type)     \
        try                                  \
        {                                    \
            (expr);                          \
            expect (false, "Expected: throws an exception of type " #type ", Actual: does not throw."); \
        }                                    \
        catch (type&)                        \
        {                                    \
            expect (true);                   \
        }                                    \
        catch (...)                          \
        {                                    \
            expect (false, "Expected: throws an exception of type " #type ", Actual: throws another type."); \
        }
 
    //==============================================================================
    void logMessage (const String& message);

    Random getRandom() const;
 
private:
    //==============================================================================
    template <class ValueType>
    void expectResultAndPrint (ValueType value, ValueType valueToCompareTo, bool result,
                               String compDescription, String failureMessage)
    {
        if (! result)
        {
            if (failureMessage.isNotEmpty())
                failureMessage << " -- ";
 
            failureMessage << "Expected value" << (compDescription.isEmpty() ? "" : " ")
                           << compDescription << ": " << valueToCompareTo
                           << ", Actual value: " << value;
        }
 
        expect (result, failureMessage);
    }
 
    //==============================================================================
    const String name, category;
    UnitTestRunner* runner = nullptr;
 
    JUCE_DECLARE_NON_COPYABLE (UnitTest)
};
 
 
//==============================================================================
class JUCE_API  UnitTestRunner
{
public:
    //==============================================================================
    UnitTestRunner();

    virtual ~UnitTestRunner();

    void runTests (const Array<UnitTest*>& tests, int64 randomSeed = 0);

    void runAllTests (int64 randomSeed = 0);

    void runTestsInCategory (const String& category, int64 randomSeed = 0);

    void setAssertOnFailure (bool shouldAssert) noexcept;

    void setPassesAreLogged (bool shouldDisplayPasses) noexcept;
 
    //==============================================================================
    struct TestResult
    {
        TestResult() = default;
 
        explicit TestResult (const String& name, const String& subCategory)
             : unitTestName (name),
               subcategoryName (subCategory)
        {
        }

        String unitTestName;
        String subcategoryName;

        int passes = 0;
        int failures = 0;

        StringArray messages;

        Time startTime = Time::getCurrentTime();
        Time endTime;
    };

    int getNumResults() const noexcept;

    const TestResult* getResult (int index) const noexcept;
 
protected:
    virtual void resultsUpdated();

    virtual void logMessage (const String& message);

    virtual bool shouldAbortTests();
 
private:
    //==============================================================================
    friend class UnitTest;
 
    UnitTest* currentTest = nullptr;
    String currentSubCategory;
    OwnedArray<TestResult, CriticalSection> results;
    bool assertOnFailure = true, logPasses = false;
    Random randomForTest;
 
    void beginNewTest (UnitTest* test, const String& subCategory);
    void endTest();
 
    void addPass();
    void addFail (const String& failureMessage);
 
    JUCE_DECLARE_NON_COPYABLE (UnitTestRunner)
};
 
} // namespace juce