Unit Tests Manual

Table of Contents

• About
• Implementation
• Registration
• Further Reading

About

maxon::UnitTestInterface provides an unified interface for any kind of unit test. Such an unit test should verify the correct functionality of every component of a program. Unit tests implemented this way are automatically executed when Cinema 4D starts and unit tests are enabled.

Implementation

Custom unit test are created by implementing a custom class based on maxon::UnitTestComponent. This custom class must implement maxon::UnitTestInterface::Run() which contains the unit test code.

The result of a test can be printed to the console using a standard format:

• maxon::UnitTestInterface::AddResult(): Prints the result to the console.
• maxon::UnitTestInterface::AddTimingResult(): Prints the result with timing to the console.

A (long running) unit test may be cancelled from the outside:

• maxon::UnitTestInterface::IsCancelled(): Returns true if the test has been cancelled.
• maxon::UnitTestInterface::Cancel(): Cancels the unit test.

Note

To measure time for speed tests one can use maxon::TimeValue.

// This example shows a unit test that checks a custom class.
 
class SimpleMathsUnitTest : public maxon::UnitTestComponent<SimpleMathsUnitTest>
{
  MAXON_COMPONENT();
 
public:
  maxon::Result<void> Run()
  {
    // test constructor / SimpleMaths::GetNumber()
    MAXON_SCOPE
    {
      const maxon::Int  number = 5;
      const SimpleMaths baseTest(number);
 
      const maxon::Result<void> baseRes = baseTest.GetNumber() == number ? maxon::OK : maxon::UnitTestError(MAXON_SOURCE_LOCATION, "GetNumber() failed"_s);
      self.AddResult("GetNumber() test"_s, baseRes);
 
      // if GetNumber() fails the rest of the unit tests cannot succeed
      if (baseRes.GetError())
        return baseRes;
    }
 
    // test SimpleMaths::AddNumber()
    MAXON_SCOPE
    {
      SimpleMaths addTest(99);
      addTest.AddNumber(1);
 
      const maxon::Result<void> addTestRes = addTest.GetNumber() == 100 ? maxon::OK : maxon::UnitTestError(MAXON_SOURCE_LOCATION, "AddNumber() failed"_s);
      self.AddResult("AddNumber() test"_s, addTestRes);
    }
 
    // test SimpleMaths::SubstractNumber()
    MAXON_SCOPE
    {
      SimpleMaths subTest(100);
      subTest.SubstractNumber(1);
 
      const maxon::Result<void> subTestRes = subTest.GetNumber() == 99 ? maxon::OK : maxon::UnitTestError(MAXON_SOURCE_LOCATION, "SubstractNumber() failed"_s);
      self.AddResult("SubstractNumber() test"_s, subTestRes);
    }
 
    return maxon::OK;
  }
};

The result of this unit test will be printed to the console:

==========================================
@Running unit test 1 / 1: net.maxonexample.unittest.simplemaths
==========================================
Unittest "net.maxonexample.unittest.simplemaths" OK: GetNumber() test
Unittest "net.maxonexample.unittest.simplemaths" OK: AddNumber() test
Unittest "net.maxonexample.unittest.simplemaths" OK: SubstractNumber() test
Duration: 0.5 ms
==========================================
@ScriptRef End

Registration

Different kinds of unit tests can be registered at these registries:

• maxon::UnitTestClasses
  • Contains pure functional tests that run in less than 2000 ms.
  • Should use identifiers in the form of net.maxonexample.unittest.mytest.
  • Invoked with the command line argument g_runUnitTests.
• maxon::SpeedTestClasses
  • Contains speed tests that run in 2000 ms or more.
  • Should use identifiers in the form of net.maxonexample.speedtestclass.mytest.
  • Invoked with the command line argument g_runSpeedTests.
• maxon::LongRunTestClasses
  • Contains functional tests that run in 2000 ms and more.
  • Should use identifiers in the form of net.maxonexample.longruntestclass.mytest.
  • Invoked with the command line argument g_runLongRunTests.

To run all unit tests set the command line argument to "*" like g_runUnitTests=*. To run a specific test one can define a filter like g_runUnitTests=*simplemaths*.

// This example registers the given unit test at the registry maxon::UnitTestClasses.
 
MAXON_COMPONENT_CLASS_REGISTER(SimpleMathsUnitTest, maxon::UnitTestClasses, "net.maxonexample.unittest.simplemaths");

Further Reading

• Error Handling
• ExecutionInterface Manual
• Configuration Variables