Unit testing

Torque 3D includes the googletest unit testing framework so you can write engine-side unit tests.

Enable unit tests

Unit testing is not enabled by default when you generate a new project; you need to select the 'unit testing' module and then regenerate your project source files.

Write unit tests

See the googletest primer for a good introduction to writing unit tests with googletest. Here's a brief example to get you started:

It is convention for all unit tests in Torque 3D to follow these rules:

  • A unit test file should typically test the contents of one other file. For example, there is a tVectorTest.cpp which tests the Vector class declared in tVector.h.
  • Test files should be named after the file they test, with a Test suffix (as in the previous example).
  • Test files should be placed in a test directory adjacent to the file they test. For example, the tests for math/mBox.h are in math/test/mBoxTest.cpp.
  • All unit tests should be wrapped in #ifdef TORQUE_TESTS_ENABLED.

We also have two custom macros for writing unit tests with fixtures, especially when these tests overlap with existing class names. These fixtures work the same way as regular googletest fixtures - for example, their SetUp methods are called before tests are run:

However, note that you cannot mix TEST_FIX and TEST cases with the same name - so either all tests for a class should use a fixture, or none, or you should come up with another name for either set of tests. Though it's probably just easiest to make all tests with TEST_FIX, even if some tests don't use the fixture data.

Run unit tests

Once you've written unit tests and compiled the engine, you need to run tests. The runAllUnitTests console method exists for this purpose. It takes one argument, which is passed to the googletest library and can be used to specify 'command-line' arguments for googletest.

We recommend using the separate runTests.cs file to do this from the console. The Full and Empty templates both include this file next to main.cs. To run the tests, open a console in your game/ directory, and type "Torque 3D.exe" runTests.cs. Note that you may need to replace "Torque 3D.exe" with the name of your executable.

The engine will start up, run all unit tests (except stress tests, which are excluded by default in runTests.cs), and print the results into your console.

TorqueScript unit tests

If you want to run unit tests in TorqueScript, not C++, Daniel selfishly recommends the use of tasman, a TorqueScript unit-testing framework inspired by Jasmine:

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License