The following setup guide will assume that you have created your project within MicroMacro's script directory; for example, C:/micromacro/scripts/my-project

First things first, you will need to create a new directory named tests in your project's root directory. Within the tests directory, you can create any many files and subdirectories as you need. By default, any file under tests with the .lua extension will be checked for tests functions. Any found function that has a name that begins with test_ will be considered a unit test function.

Your project directory might look something like this:

my-project/
    main.lua
    utils.lua
    tests/
        test_utils.lua

Now that our project structure is set up, we can begin writing unit tests in tests/test_utils.lua, or any other file underneath tests if we wish.

Finally, we can run our unit tests by entering the command when prompted:

If everything went according to plan, we should see that our unit test function was run and passed all checks:

Running tests
 [PASS]  test_utils.lua::test_my_first_unit_test ............... 0.00ms

Tests: 1, Assertions: 1, Passed: 1, Failed: 0

A few things to remember:

• You must place your unit test files in a directory named tests in your project root.
• You should name your test files with the .lua extension to ensure they are checked by default.
• Your test files, other than extension, can be named anything you would like, but it is generally good practice to name them starting with test_ and follow with a useful description, indicating what functionalities it tests.
• You may create additional subdirectories under tests to organize your test files.
• Your test files may have many test functions within them.
• Your test files may also have non-test functions; any function that has a name that does not begin with test_
• Each test function should have one or more assertion. See writing unit tests for more details.
• While you may have multiple assertions in your test functions, each test function should test only one principal (ie. test the unit).

Inside each test function, you should have one or more assertion. These can be as simple as making use of Lua's built-in assert() function, or using a variety of MicroMacro's available assertions.

To make use of MicroMacro's assertions, your test function should accept an instance of the Assert class and call one of the available assertions on it. See below for examples.

Unit tests can be run by invoking the test command and passing the root directory to your project as the first argument. For example, if your project directory is named my-project and resides in MicroMacro's scripts directory, you may use test my-project.

You may also provide some additional options to this command. --verbose may be used to provide more detailed output (if available), and --filter-files may be used to override which file(s) to scan for.