axmol/tests/unit-tests/README.md

unit-tests

Description

unit-tests app is a console application that runs Axmol's automated unit tests. It can be used for test driven development, checking for regressions during development, or running tests in a CI/CD pipeline.

One of the unit-tests goals is for it to be fast, so it can be run frequently during development.

Setup

The unit-tests app is a console app. For writting tests unit-tests uses doctest library. It's pretty simple and easy to use.

Usage

Supported platforms:

• Linux
• macOS
• Windows

To run tests simply build the unit-tests app and run it. It will run all tests automatically and print the results to the console. The app also returns error code 0 if all tests pass and non 0 code if any test fails.

Use axmol build -d tests/unit-tests for building the unit-tests app. Then use command line to run the app. You can also run it with unit-tests --help to see all available options.

Writing tests

Adding new tests

Let's say you want to write unit tests for ax::Node class. To add a new test follow these steps:

1. Find or create a source file to hold your tests. For easier navigation test source files follow the same layout and naming as the engine source files, and only add a Tests postfix. For example ax::Node in engine is in core/2d/Node.h, so the test file should be in tests/unit-tests/Source/core/2d/NodeTests.cpp.

2. If the file doesn't exist, then create a new file, in this case tests/unit-tests/Source/core/2d/NodeTests.cpp.

3. Register new file in tests/unit-tests/CMakeLists.txt.

4. For the test file use the following structure:

   // <add copyright message here>
   #include <doctest.h>
   #include "2d/Node.h" // Include the thing you're testing
   
   USING_NS_AX;
   
   // For suite name use the part of the source file path, in this case `2d` followed by the
   // class name you will be testing, in this case `Node`. Separate the parts with a slash.
   TEST_SUITE("2d/Node") {
   }
   

5. If you will be testing functions, methods or their groups, then use their names in the test case like this:

    TEST_SUITE("2d/Node") {
        TEST_CASE("addChild") {
            // addChild() tests go here
        }
   
   
        TEST_CASE("removeFromParent") {
            // removeFromParent() tests go here
        }
    }
   

6. If you will be testing some specific functionality, then name what you're testing like this:

    TEST_SUITE("2d/Node") {
        TEST_CASE("adding_child_clears_dirty_flag") {
            // Test goes here
        }
    }
   

7. TestUtils.h header contains some helpers for testing.

8. For reference example see FileUtils tests in tests\unit-tests\Source\core\platform\FileUtilsTests.cpp.

Writing tests

For more information on how to write tests using doctest, see the doctest documentation

Things to keep in mind

• For suite, case or subcase names use only a-zA-Z0-9_/[] symbols for easier use in command line.
• Try to follow the established naming and structure for suites and cases. This is for easier filtering when running tests.