Modules Testing Framework

Testing Framework

Module's testing framework is based on a widely known Lua unit testing framework called Busted. All third-party libraries needed to run unit tests are placed into /tests_framework folder.

In addition to base testing framework there is a package "utils/mock" which gives fully working environment to a module and imitate communication of the module and agent as well as give full access to vxapi needed in module logic.

Unit-tests structure

It is recommended to use the following approach to store unit tests:

Naming: {module_name}_{module_side}_spec.lua, where module_name is a full name of the module and module_side is either client or server.

Tests placement: folder /tests in the Soldr-modules repository.

Common test structure (full-featured example can be found here):

require 'busted.runner' ()

...

describe('file_remover agent', function()
    setup(function()
        _G.__mock = {
            vars = {},
            timeout = 2,
            cwd = "tmpcwd",
            module = "file_remover",
            version = "1.0.0",
            side = "agent",
            log_level = os.getenv("LOG_LEVEL") or "debug",
        }
        -- load mocked environment
        require("mock")
        __mock:module_start()
    end)

    teardown(function()
        __mock:module_stop()
    end)

    before_each(function()
        __mock:clear_expectations()
    end)

    describe('file remover module', function()
        it('should delete file using module functionlity', function()
            local src, dst = __mock.mock_token, __mock.module_token
            local test_file_path = new_test_file()

            local action_data = filepath_to_json('object.fullpath', test_file_path)
            assert.is_true(file_exists(test_file_path), "test file is not found")

            -- ask module to delete the file
            assert(__mock:send_action(src, dst, action_data, "fr_remove_object_file"),
                "failed to send file remove action")
            -- wait for expected result to arrive (in any order)
            assert.is_true(__mock:expect("event",
                function(o) return o.event and o.event.name == "fr_object_file_removed_successful" end))
            assert.is_true(__mock:expect("data", function(o) return o.data and o.data.name == "fr_remove_object_file" end))

            -- check that file was actually removed
            assert.is_false(file_exists(test_file_path), "test file was not removed by a module")
        end)
    end)
end)

Legend:

"describe" - testable object definition
"setup" - initialization of the module
"teardown" - module shutdown
"it" - test scenarios definition
"__mock:send_action", "__mock:send_data" - communication with module
"__mock:expect" - waiting for some data to get back from modules

Tests starting

First download modules source code:

git clone git@github.com:vxcontrol/soldr-modules.git
cd soldr-modules
git submodule init
git submodule update
cd luapower/
./mgit clone git@github.com:vxcontrol/soldr-luapower-repos.git
./mgit clone-all

Unit tests can be started directly from the terminal:

cd soldr-modules

export LUAPOWER_PLATFORM=osx64
export LUA_PATH="$(pwd)/tests_framework/lua/?.lua;$(pwd)/tests_framework/lua/?/init.lua;$(pwd)/luapower/?.lua;$(pwd)/luapower/?/init.lua;$(pwd)/utils/?.lua;$(pwd)/utils/?/init.lua"
export LUA_CPATH="$(pwd)/luapower/bin/$LUAPOWER_PLATFORM/lib?.dylib;$(pwd)/luapower/bin/$LUAPOWER_PLATFORM/clib/?.so;"
export LUA_BIN="$(pwd)/luapower/bin/$LUAPOWER_PLATFORM/luajit-bin"

./tests_framework/lua/bin/busted.$LUAPOWER_PLATFORM.cmd tests/.

Also, it is possible to start tests using Busted plugin in VSCode, check this page for more information on how to configure VSCode for modules development.