waf_unit_test

Unit testing system for C/C++/D and interpreted languages providing test execution:

  • in parallel, by using waf -j
  • partial (only the tests that have changed) or full (by using waf --alltests)

The tests are declared by adding the test feature to programs:

def options(opt):
        opt.load('compiler_cxx waf_unit_test')
def configure(conf):
        conf.load('compiler_cxx waf_unit_test')
def build(bld):
        bld(features='cxx cxxprogram test', source='main.cpp', target='app')
        # or
        bld.program(features='test', source='main2.cpp', target='app2')

When the build is executed, the program ‘test’ will be built and executed without arguments. The success/failure is detected by looking at the return code. The status and the standard output/error are stored on the build context.

The results can be displayed by registering a callback function. Here is how to call the predefined callback:

def build(bld):
        bld(features='cxx cxxprogram test', source='main.c', target='app')
        from waflib.Tools import waf_unit_test
        bld.add_post_fun(waf_unit_test.summary)

By passing –dump-test-scripts the build outputs corresponding python files (with extension _run.py) that are useful for debugging purposes.

waflib.Tools.waf_unit_test.handle_ut_cwd(self, key)[source]

Task generator method

Task generator method, used internally to limit code duplication. This method may disappear anytime.

waflib.Tools.waf_unit_test.make_interpreted_test(self)[source]

Task generator method

Create interpreted unit tests.
feature:test_scripts
waflib.Tools.waf_unit_test.make_test(self)[source]

Task generator method

Create the unit test task. There can be only one unit test task by task generator.
feature:test
waflib.Tools.waf_unit_test.add_test_results(self, tup)[source]

Task generator method

Override and return tup[1] to interrupt the build immediately if a test does not run

class waflib.Tools.waf_unit_test.utest(*k, **kw)[source]

Bases: waflib.Task.Task

Execute a unit test

color = 'PINK'
after = ['vnum', 'inst']
vars = []
runnable_status()[source]

Always execute the task if waf –alltests was used or no tests if waf --notests was used

get_test_env()[source]

In general, tests may require any library built anywhere in the project. Override this method if fewer paths are needed

run()[source]

Execute the test. The execution is always successful, and the results are stored on self.generator.bld.utest_results for postprocessing.

Override add_test_results to interrupt the build

hcode = '\tdef run(self):\n\t\t"""\n\t\tExecute the test. The execution is always successful, and the results\n\t\tare stored on ``self.generator.bld.utest_results`` for postprocessing.\n\n\t\tOverride ``add_test_results`` to interrupt the build\n\t\t"""\n\t\tif hasattr(self.generator, \'ut_run\'):\n\t\t\treturn self.generator.ut_run(self)\n\n\t\tself.ut_exec = getattr(self.generator, \'ut_exec\', [self.inputs[0].abspath()])\n\t\tut_cmd = getattr(self.generator, \'ut_cmd\', False)\n\t\tif ut_cmd:\n\t\t\tself.ut_exec = shlex.split(ut_cmd % \' \'.join(self.ut_exec))\n\n\t\treturn self.exec_command(self.ut_exec)\n'
waflib.Tools.waf_unit_test.summary(bld)[source]

Display an execution summary:

def build(bld):
        bld(features='cxx cxxprogram test', source='main.c', target='app')
        from waflib.Tools import waf_unit_test
        bld.add_post_fun(waf_unit_test.summary)
waflib.Tools.waf_unit_test.set_exit_code(bld)[source]

If any of the tests fail waf will exit with that exit code. This is useful if you have an automated build system which need to report on errors from the tests. You may use it like this:

def build(bld):
bld(features=’cxx cxxprogram test’, source=’main.c’, target=’app’) from waflib.Tools import waf_unit_test bld.add_post_fun(waf_unit_test.set_exit_code)
waflib.Tools.waf_unit_test.options(opt)[source]

Provide the --alltests, --notests and --testcmd command-line options.

waflib.Tools.waf_unit_test.feature(*k)

Decorator that registers a task generator method that will be executed when the object attribute feature contains the corresponding key(s):

from waflib.Task import feature
@feature('myfeature')
def myfunction(self):
        print('that is my feature!')
def build(bld):
        bld(features='myfeature')
Parameters:k (list of string) – feature names
waflib.Tools.waf_unit_test.taskgen_method(func)

Decorator that registers method as a task generator method. The function must accept a task generator as first parameter:

from waflib.TaskGen import taskgen_method
@taskgen_method
def mymethod(self):
        pass
Parameters:func (function) – task generator method to add
Return type:function
waflib.Tools.waf_unit_test.after_method(*k)[source]

Decorator that registers a task generator method which will be executed after the functions of given name(s):

from waflib.TaskGen import feature, after
@feature('myfeature')
@after_method('fun2')
def fun1(self):
        print('feature 1!')
@feature('myfeature')
def fun2(self):
        print('feature 2!')
def build(bld):
        bld(features='myfeature')
Parameters:k (list of string) – method names

Features defined in this module: